Zinnector® 문제 해결

실제 사용자가 Zinnector® CLI를 사용하면서 겪는 오류들과 각각의 의미, 그리고 해결 방법입니다. 각 항목에는 화면에 표시되는 정확한 텍스트가 명시되어 있으므로 이 페이지에서 검색할 수 있습니다. 만약 여기에 없는 오류가 발생한다면, 실패한 명령어를 ZINNECTOR_DEBUG=1과 함께 실행한 후 그 출력값, 사용 중인 node --version, 그리고 운영체제를 포함하여 github.com/Zinn-Digital/zinnector/issues에 이슈를 남겨 주시기 바랍니다.

런타임 설치 수락 직후의 "spawn EINVAL" (Windows)

Zinnector® 0.1.0 및 0.1.1의 버그입니다. Windows 환경에서 런타임 설치 프로그램이 이름으로 npm.cmd를 실행했는데, Node는 CVE-2024-27980에 대한 수정 이후 셸 없이는 .cmd 파일의 생성을 거부하므로 사용자가 Y라고 답한 지 1초 만에 설치가 중단되었습니다. 0.1.2 버전에서 수정됨: 이제 npm이 모든 플랫폼에서 동일하며 셸이 필요 없는 node npm-cli.js로 실행됩니다. npm install -g zinnector@latest를 실행한 후 zinnector dev를 다시 실행하십시오.

설치 중 "npm WARN EBADENGINE" 또는 "Zinnector® needs Node 24 or newer"

사용 중인 Node 버전이 24 미만입니다. 패키지가 engines: >=24.18.1을 선언하고 있기 때문에 npm이 이 경고를 출력하는 것이며, 설치는 완료되지만 나중에 혼동을 주는 곳에서 실패하기보다 시작 단계에서 zinnector가 거부(종료 코드 78)하게 됩니다. nodejs.org에서 최신 LTS 버전을 설치하고(Windows의 경우 winget install OpenJS.NodeJS.LTS, macOS의 경우 brew install node@24), node --version 실행 시 v24 이상이 출력되는지 확인한 뒤 Zinnector®를 다시 설치하십시오.

"gyp ERR!", "Building from source with node-gyp", 또는 "You need to install Visual Studio"

WordPress 런타임에는 Node 24 및 25 전용으로 미리 빌드된 바이너리가 존재하는 네이티브 모듈이 포함되어 있습니다. (2026년 9월 기준) 최신 Node 버전(26 이상)에서는 설치 프로그램이 소스 코드 컴파일로 대체되며, 일반 Windows 머신에서는 Visual Studio 설치 요청으로 이어지게 됩니다. 0.1.2 버전에서 수정됨: Zinnector®가 어떤 것을 다운로드하기 전에 이를 감지하여 런타임 전용으로 Node 24를 가져오므로(nodejs.org의 체크섬으로 검증된 약 30MB) 소스가 컴파일되는 일은 전혀 없습니다. 업그레이드 후에도 이 문제가 계속 발생한다면 zinnector dev --reset-runtime을 실행하여 이전의 반쯤 완료된 설치를 먼저 삭제하십시오.

npm이 정리 작업을 수행하는 동안 발생하는 "EPERM" 경고 (Windows)

대부분 안티바이러스 스캐너나 검색 색인 생성기가 런타임의 node_modules 아래에 있는 파일을 열어 둔 상태에서 npm이 이를 제거하려고 할 때 발생합니다. 다음 zinnector dev 실행 시 깨끗한 디렉토리에서 설치가 다시 시도되며, 문제가 지속될 경우 zinnector dev --reset-runtime을 실행하면 전체 런타임 디렉토리를 먼저 삭제하고 다시 설치합니다.

"the local playground runtime could not be installed"

이 메시지에는 npm의 마지막 출력 줄들과 Zinnector®가 실행한 정확한 명령어가 포함되어 있으므로, 직접 실행하여 전체 출력 결과를 확인할 수 있습니다. 일반적인 원인은 네트워크나 프록시 문제(런타임은 사용자의 npm을 통해 가져오므로 npm config set proxy … 및 레지스트리 미러가 적용됨) 또는 반쯤 완료된 이전 설치 건이며, 이는 --reset-runtime으로 지울 수 있습니다.

"the local playground exited before it was ready", 또는 준비 상태가 되지 않는 경우

zinnector dev --verbose를 실행하여 런타임 자체의 출력을 확인하십시오. 흔한 원인은 이미 사용 중인 포트입니다: zinnector dev --port 9401을 사용하거나 zinnector.json에서 port를 설정하십시오. 설치는 되었지만 부팅되지 않는 런타임의 경우: zinnector dev --reset-runtime을 실행하십시오. 첫 부팅 시 WordPress 자체도 다운로드하므로 느린 연결 환경인 경우 몇 분 정도 기다려 주시기 바랍니다. CLI는 타임아웃 발생 전 중단되는 대신 최대 5분까지 대기합니다.

푸시 시 발생하는 "this project is not a git repository"

배포는 저장소를 기반으로 진행되므로 zinnector push에는 플랫폼이 접근할 수 있는 원격소가 있는 저장소가 필요합니다. git init && git add -A && git commit -m initial을 실행하고 GitHub 또는 GitLab 원격소를 추가한 다음, zinnector link를 실행하여 사이트에 연결하십시오.

배포 후 사이트가 하얗게 나오는 경우

zinnector check를 실행하십시오. 열 중 아홉은 PHP 버전 차이(슬롯이 실행하는 버전보다 더 최신 PHP로 빌드한 경우) 때문이며, 보고서는 슬롯을 전환할 PHP 버전을 zinnector php <version>으로 안내하거나 개발에 사용할 버전을 zinnector dev --php <version>으로 안내합니다. zinnector logs --error를 통해 치명적 오류 내용을 확인할 수 있습니다.