使用 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 的镜像，并且支持 7.4 到 8.5 的 PHP 版本——但它运行的是带有完整扩展集（包括 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 构建版本的软件包大约为 570 MB，而一个仅仅列出网站的开发者不应为之买单。它保存在 Zinnector® 自己的缓存中，即 ~/.cache/zinnector/runtimes/playground/<version>（或者 ZINNECTOR_CACHE_DIR 指向的位置），绝不会保存在您的项目中，因此它不会最终进入您的代码仓库或 zinnector push 所测量的目录树中。下载是由您自己的 npm 完成的，以 node npm-cli.js 的方式运行——绝不通过 shell。

运行时版本与 CLI 版本绑定，因此同一个项目中的两个开发人员可以运行相同的 PHP 构建。zinnector dev --reset-runtime 会丢弃已安装的运行时并重新安装它，这是解决已安装但无法启动的运行时的方法。

在 Node 26 或更新版本上

CLI 本身可以在从 24 开始的任何 Node 上运行。然而，运行时的原生模块仅为 Node 24 和 25（截至 2026 年 9 月）预构建了二进制文件。Zinnector® 不会编译任何内容（在 Windows 上这意味着安装 Visual Studio），而是会专门为运行时获取一个大约 30 MB 的 Node 24，并通过 nodejs.org 发布的校验和进行验证，存入相同的缓存中。安装提示在应用时会说明这一点。关于您自己的 Node 的任何内容都不会改变。