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 파일을 생성(spawn)하는 것을 거부하여 사용자가 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용으로만 사전 빌드된 바이너리가 제공되는 네이티브 모듈이 포함되어 있습니다. 더 최신 버전의 Node(2026년 9월 기준 26 이상)에서는 설치 프로그램이 소스 코드 컴파일 방식으로 대체 실행되며, 일반적인 Windows 환경에서는 Visual Studio 설치 요청으로 이어집니다. 0.1.2에서 수정됨: Zinnector®는 파일을 다운로드하기 전에 이를 감지하여 아무것도 컴파일되지 않도록 런타임 전용 Node 24(약 30MB, nodejs.org의 체크섬 검증 완료)를 가져옵니다. 업그레이드 후에도 이 문제가 계속 발생한다면 zinnector dev --reset-runtime을 실행하여 이전에 완료되지 않은 설치 파일을 먼저 삭제해 주십시오.

npm 정리 작업 중 "EPERM" 경고 발생 (Windows)

대부분 npm이 파일을 제거하려는 동안 백신 프로그램이나 검색 인덱서가 런타임의 node_modules 아래에 있는 파일을 점유하고 있어 발생합니다. 다음번 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 환경에서 빌드한 경우이며, 리포트를 통해 zinnector php <version>으로 슬롯의 버전을 전환해야 하는지, 혹은 zinnector dev --php <version>으로 개발 환경의 버전을 맞춰야 하는지 확인할 수 있습니다. zinnector logs --error를 실행하면 치명적 오류(fatal error) 자체를 확인할 수 있습니다.

관련 문서

• 시작하기 · 로컬 개발 · 배포 · 명령어 참조