故障排除 Zinnector®

人们在使用 Zinnector® CLI 时实际遇到的错误、每个错误含义以及修复方法。每个条目都列出了您将看到的具体文本，以便您可以在此页面上进行搜索。如果这里没有您的错误，请带上 ZINNECTOR_DEBUG=1 运行失败的命令，并在 github.com/Zinn-Digital/zinnector/issues 上提交一个 issue，并附上输出结果、您的 node --version 以及您的操作系统。

接受运行时安装后立即出现 "spawn EINVAL"（Windows）

这是 Zinnector® 0.1.0 和 0.1.1 中的一个 bug。在 Windows 上，运行时安装程序按名称运行了 npm.cmd，而自 CVE-2024-27980 的修复补丁发布以来，Node 一直拒绝在没有 shell 的情况下派生（spawn）.cmd 文件——因此安装在您回答 Y 的一秒钟后崩溃了。已在 0.1.2 中修复： npm 现在作为 node npm-cli.js 运行，这在所有平台上都是相同的，并且不需要 shell。请运行 npm install -g zinnector@latest，然后再次运行 zinnector dev。

安装期间出现 "npm WARN EBADENGINE"，或 "Zinnector® needs Node 24 or newer"

您的 Node 版本低于 24。npm 会打印此警告，因为该软件包声明了 engines: >=24.18.1；安装无论如何都会完成，但随后 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（约 30 MB，已对照 nodejs.org 的校验和进行验证）——因此永远不会编译任何内容。如果您在升级后仍然看到此错误，请运行 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 会等待最多五分钟才报告超时，而不会挂起。

推送时出现 "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 版本比插槽（slot）运行的版本更新——报告会说明应该使用 zinnector php <version> 将插槽切换到哪个版本，或者应该针对哪个版本进行开发 zinnector dev --php <version>。zinnector logs --error 会显示致命错误本身。