zinnector dev를 이용한 로컬 개발

zinnector dev 명령어는 사용자의 컴퓨터에서 실제 WordPress를 실행하며, 선택한 PHP 버전으로 프로젝트의 플러그인과 테마를 서비스합니다. 본 기사에서는 이 명령어가 사용할 수 있는 두 가지 런타임, 버전 선택 방법, 서비스 제공 방식, 그리고 디스크 상에서 런타임이 위치하는 곳을 설명합니다. 이를 통해 로컬에서 테스트한 내용이 그대로 배포되도록 합니다.

두 가지 런타임과 둘 다 실제 작동하는 이유

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

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

zinnector dev                       # playground
zinnector dev --runtime docker      # native 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 빌드를 포함하는 패키지는 약 570 MB이므로, 단순히 사이트 목록만 조회하는 개발자가 이를 감당할 필요는 없습니다. 이 파일은 프로젝트 내에 저장되지 않고 Zinnector®의 자체 캐시인 ~/.cache/zinnector/runtimes/playground/<version>(또는 ZINNECTOR_CACHE_DIR가 가리키는 위치)에 보관되므로, 리포지토리나 zinnector push가 측정하는 트리 구조에 포함되지 않습니다. 다운로드는 셸을 거치지 않고 node npm-cli.js로 실행되는 사용자의 npm을 통해 수행됩니다.

런타임 버전은 CLI 버전과 고정되어 있으므로, 한 프로젝트의 두 개발자는 동일한 PHP 빌드를 실행하게 됩니다. zinnector dev --reset-runtime은 설치된 런타임을 삭제하고 다시 설치하며, 이는 설치되었으나 부팅되지 않는 런타임을 해결하기 위한 방법입니다.

Node 26 이상 버전 사용 시

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