개발자용 CLI인 Zinnector® 시작하기

Zinnector®은(는) WordPress 개발자를 위한 Zinn Digital®의 무료 MIT 라이선스 명령줄 도구입니다. 사이트를 스캐폴딩하고, Node 외에는 아무것도 설치되어 있지 않은 로컬 머신에서 실제 WordPress를 실행하며(Docker, MAMP, PATH상의 PHP 없음), 배포할 호스팅 슬롯과 비교하여 빌드된 내용을 확인한 후 푸시합니다. 이 가이드는 아무것도 없는 상태에서 약 2분 만에 실행 중인 사이트를 만들 수 있도록 안내하며, 각 단계에서 성공적인 상태가 어떤 모습인지 알려주어 문제가 발생했을 때 이를 파악할 수 있도록 합니다.

준비물

Node 24 이상. node --version을 실행하세요. 결과로 v24 이상이 출력되어야 합니다. nodejs.org에서 최신 LTS 버전을 설치하세요(Windows의 경우 winget install OpenJS.NodeJS.LTS, macOS의 경우 brew install node@24).
npm: Node에 기본 포함되어 있습니다. Zinnector®는 WordPress 런타임을 자체 캐시에 다운로드하기 위해 이를 한 번 사용합니다.
git: zinnector push를 사용할 때만 필요하며, 배포는 저장소에서 구동됩니다.
Docker: --runtime docker를 명시적으로 요청한 경우에만 필요합니다. 기본 런타임에는 필요하지 않습니다.

아래 내용 중 계정이 필요한 것은 없습니다. API 키는 호스팅 슬롯에 도달했을 때 Zinnector®로 배포하기에서만 필요합니다.

1단계 — 설치하기

npm install -g zinnector

npm이 npm WARN EBADENGINE을 출력하는 경우, 현재 사용 중인 Node 버전이 패키지에서 요구하는 >=24.18.1보다 낮습니다. 설치는 완료되지만 CLI가 실행을 거부합니다. 먼저 Node를 업그레이드한 후 다시 설치하세요.

2단계 — 버전 확인하기

zinnector --version

성공: 0.1.2와 같은 버전 번호가 출력됩니다. "Zinnector® needs Node 24 or newer — this is Node 20.x" 메시지가 표시되면 바이너리는 설치되었으나 Node 버전이 너무 낮다는 의미이며, 명령어가 아무 작업도 수행하지 않고 코드 78로 종료됩니다.

3단계 — 도움말 읽기

zinnector --help

성공: 흐름에 사용되는 5가지 명령어(new, dev, link, check, push)의 이름을 나열하는 배너와 각 명령어의 한 줄 목적이 표시됩니다. 모든 명령어는 개별적인 --help도 지원합니다(예: zinnector dev --help는 런타임, PHP, 포트 플래그를 나열합니다). 예제가 포함된 전체 목록은 명령어 참조에서 확인할 수 있습니다.

4단계 — 사이트 스캐폴딩하기

zinnector new my-site

성공: Created my-site 제목과 작성된 파일 목록(zinnector.json, plugins/, themes/, mu-plugins/ 헬퍼가 포함된 wp-content 트리, .gitignore 및 README)과 함께 다음에 실행할 명령어가 표시됩니다. 여기에는 플레이스홀더가 없으며, 프로젝트가 있는 그대로 부팅됩니다. --template plugin 또는 --template theme을 사용하면 생성되는 즉시 활성화되는 플러그인 또는 블록 테마를 스캐폴딩합니다.

5단계 — 실행하기

cd my-site
zinnector dev

최신 버전이 아닐 경우, Zinnector®는 처음 실행 시 WordPress 런타임(5.2부터 8.5까지의 모든 PHP 빌드를 포함하므로 약 570MB)을 프로젝트가 아닌 자체 캐시 디렉터리에 다운로드하기 전에 한 번 확인을 요청합니다. Y를 입력하거나 --yes를 전달하여 이 질문을 건너뛸 수 있습니다. Node 26 이상에서는 런타임 전용 Node 24(nodejs.org의 체크섬으로 검증된 약 30MB)도 함께 가져오는데, 이는 런타임의 네이티브 모듈에 Node 24 및 25용으로 사전 빌드된 바이너리만 포함되어 있기 때문입니다. 컴파일러나 Visual Studio는 필요하지 않습니다.

성공: 프로젝트 이름, PHP 버전, WordPress 버전이 표시된 블록과 다음 내용이 출력됩니다:

✔ running at http://127.0.0.1:9400
  admin: http://127.0.0.1:9400/wp-admin  (already signed in)

6단계 — 열기

브라우저에서 http://127.0.0.1:9400을 방문하세요. 성공: 요청한 PHP 버전으로 서빙되는 My WordPress Website 제목의 새로운 WordPress 사이트가 표시됩니다. http://127.0.0.1:9400/wp-admin은 이미 로그인된 상태로 대시보드를 엽니다. wp-content/plugins/에 플러그인을 넣거나 wp-content/themes/에 테마를 넣으면 다음 새로고침 시 바로 반영됩니다. 런타임은 프로젝트에서 직접 해당 디렉터리를 서빙합니다.

중지하려면 Ctrl-C를 누르세요. zinnector dev --once는 런타임을 부팅하고 실제로 실행 중인 항목(PHP 버전, WordPress 버전, 로드된 확장 기능)을 출력한 뒤 중지합니다. 이는 약속이 아닌 증거를 원할 때 유용합니다.

다음 단계

zinnector dev로 로컬 개발하기 — 두 가지 런타임, PHP 및 WordPress 버전 선택, 그리고 무엇이 어디서 서빙되는지 설명합니다.
Zinnector®로 배포하기 — 로그인, 프로젝트를 슬롯에 연결, 사전 비행 점검(pre-flight), 푸시 방법.
명령어 참조 — 모든 명령어, 플래그 및 예제.
문제 해결 — 사용자가 실제로 겪는 오류와 각각의 해결 방법.

동일한 문서는 npm 및 GitHub의 패키지 README에서도 확인할 수 있으며, 이슈와 풀 리퀘스트는 언제나 환영합니다.