zinnector dev를 사용한 로컬 개발

zinnector dev는 사용자가 선택한 PHP 버전과 함께 프로젝트의 플러그인 및 테마를 제공하며 로컬 머신에서 실제 WordPress를 실행합니다. 본 문서에서는 사용할 수 있는 두 가지 런타임, 버전 선택 방법, 제공되는 리소스의 위치, 그리고 디스크 내 런타임 저장 위치를 설명하여 로컬에서 테스트한 내용이 그대로 배포되도록 돕습니다.

두 가지 런타임과 둘 다 실제 환경인 이유

Playground가 기본값입니다. WordPress Playground는 PHP를 WebAssembly로 컴파일하여 Node 내부에서 실행하므로, Node만 설치된 노트북에서도 몇 초 만에 WordPress를 구동합니다. 5.2부터 8.5까지의 모든 PHP 버전을 사용할 수 있습니다. 현재 빌드 기준으로 측정된 소규모 PHP 확장 모듈 집합(intl, redis, memcached)을 포함하고 있으며, 이는 대부분의 플러그인 및 테마 작업에 충분합니다.

Docker는 네이티브 php-fpm 및 MariaDB 컨테이너를 실행합니다. 속도가 더 느리고, Docker 데몬과 약 1.2GB의 이미지가 필요하며, PHP 7.4부터 8.5까지 지원하지만, imagick 및 gd를 포함한 전체 확장 모듈 세트가 포함된 네이티브 PHP를 실행합니다. WebAssembly 빌드에 포함되지 않은 확장 모듈을 테스트해야 할 때 가장 확실한 해결책입니다.

zinnector dev                       # playground
zinnector dev --runtime docker      # 네이티브 PHP + MariaDB

Docker로 자동으로 조용히 전환되는 일은 절대 없습니다. 자신이 WebAssembly를 사용 중이라고 생각하지만 실제로는 Docker를 사용하고 있는 개발자는 도움을 주려던 도구로부터 잘못된 결과를 제공받은 셈이 되므로, 반드시 명시적으로 지정하여 요청해야 합니다.

PHP 및 WordPress 버전 선택하기

zinnector dev --php 8.1 --wp 6.7    # 특정 버전 조합을 대상으로 개발
zinnector dev --port 9401           # 9400 포트가 이미 사용 중인 경우
zinnector dev --no-login            # wp-admin에 자동으로 로그인하지 않음
zinnector dev --verbose             # 런타임 자체의 출력 결과 표시

기본값은 프로젝트 내 zinnector.json의 php, wordpress, runtime, port에서 가져옵니다. 이 파일은 zinnector new 명령어로 생성되며 프로젝트의 모든 구성원이 동일한 버전을 실행할 수 있도록 커밋해야 합니다. 해당 실행에 한해 명령줄 플래그가 파일 설정보다 우선 적용됩니다.

사용자가 선언한 버전과 실제로 실행되는 버전은 서로 다른 사실입니다. zinnector dev --once는 런타임을 구동하고 실제로 보고된 내용(PHP 버전, WordPress 버전, 로드된 확장 모듈)을 출력한 후 종료됩니다. zinnector check --probe 역시 프로젝트를 호스팅 슬롯과 비교할 때 동일한 측정 방식을 사용합니다.

프로젝트에서 제공되는 항목

런타임은 프로젝트의 wp-content/plugins, wp-content/themes, wp-content/mu-plugins 디렉터리를 직접 마운트하므로, 파일을 저장하면 다음 새로고침 시 바로 반영됩니다. 존재하지만 실제 콘텐츠가 없는 디렉터리는 의도적으로 마운트되지 않습니다. 비어 있는 themes/ 디렉터리를 런타임 자체 테마 위에 마운트하면 WordPress에 테마가 전혀 남지 않아 실제 사이트 대신 빈 500 오류 화면이 표시되기 때문입니다. 이것이 바로 스캐폴드가 .gitkeep 파일이 포함된 빈 디렉터리를 유지하는 이유이며, 사용자가 테마를 추가하기 전까지는 다른 항목을 가리지 않는 이유입니다.

런타임 저장 위치

WordPress 런타임은 CLI와 함께 제공되지 않고 최초 사용 시 다운로드됩니다. 모든 PHP 빌드를 포함하는 패키지는 약 570MB이며, 사이트 목록 조회만 수행하는 개발자가 이 용량을 부담해서는 안 되기 때문입니다. 이 파일은 프로젝트 내부가 아닌 Zinnector® 자체 캐시인 ~/.cache/zinnector/runtimes/playground/<version>(또는 ZINNECTOR_CACHE_DIR이 가리키는 위치)에 보관되므로, 저장소나 zinnector push가 측정하는 트리에 포함되지 않습니다. 다운로드는 셸을 통하지 않고 사용자의 자체 npm을 통해 node npm-cli.js로 실행되어 수행됩니다.

런타임 버전은 CLI 버전에 고정되어 있으므로 한 프로젝트의 두 개발자가 동일한 PHP 빌드를 실행하게 됩니다. zinnector dev --reset-runtime은 설치된 런타임을 삭제하고 다시 설치하므로, 설치는 되었으나 구동되지 않는 런타임 문제를 해결할 수 있습니다.

Node 26 이상 버전 환경

CLI 자체는 24 이상의 모든 Node 버전에서 실행됩니다. 그러나 런타임의 네이티브 모듈은 2026년 9월 기준으로 Node 24 및 25 전용 사전 빌드된 바이너리만 제공합니다. 윈도우 환경에서 Visual Studio를 설치해야 하는 등의 컴파일 과정을 거치는 대신, Zinnector®는 런타임 전용으로 사용할 약 30MB 크기의 Node 24를 nodejs.org에서 게시한 체크섬으로 검증하여 동일한 캐시로 가져옵니다. 해당되는 경우 설치 프롬프트에 안내 메시지가 표시됩니다. 사용자의 자체 Node 설정은 전혀 변경되지 않습니다.

관련 문서

• 시작하기 · 배포하기 · 명령어 참조 · 문제 해결