wp-playground

WordPress Playground

适用场景

• 快速启动一次性 WordPress，在无需搭建完整技术栈的情况下测试插件／主题。
• 在本地运行或迭代 Playground Blueprints（JSON）。
• 构建可复现的网站快照，用于分享或 CI。
• 快速切换 WP／PHP 版本以复现问题。
• 在独立的 Playground 环境中使用 Xdebug 调试插件／主题代码。

所需输入

• 主机环境就绪：Node.js ≥ 20.18，且可使用 npm/npx。
• 要挂载的项目路径（--auto-mount 或显式挂载映射）。
• 期望的 WP 版本／PHP 版本（可选；默认使用最新 WP 和 PHP 8.3）。
• 运行 Blueprint 时所需的 Blueprint 路径／URL。
• 如果 9400 端口冲突，需指定首选端口。
• 是否需要 Xdebug。

流程

0）注意事项

• Playground 实例是临时的，使用 SQLite；切勿指向生产数据。
• 运行 CLI 前，确认 Node ≥ 20.18（node -v）。
• 如果挂载本地代码，请确保其中不含机密；Playground 会将文件复制到内存文件系统中。

1）快速在本地启动（自动挂载）

cd <plugin-or-theme-root>
npx @wp-playground/cli@latest server --auto-mount

• 默认在 http://localhost:9400 打开。自动检测插件／主题并安装。
• 根据需要添加 --wp=<version> / --php=<version>。
• 对于已经存在的传统完整安装，添加 --skip-wordpress-setup 并挂载整个目录树。

2）手动挂载或多重挂载

• 自动挂载不够用时（多个插件、mu-plugins、自定义内容），使用 --mount=/host/path:/vfs/path（可重复指定）。
• 使用 --mount-before-install 在安装前挂载，以引导安装程序流程。
• 参考：references/cli-commands.md

3）运行 Blueprint（无需服务）

npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>

• 适用于脚本化设置／CI 验证。支持远程 URL 和本地文件。
• 需要时，使用 --blueprint-may-read-adjacent-files，允许本地 Blueprint 读取捆绑的资源。
• Blueprint 结构和常用标志参见 references/blueprints.md。

4）构建快照以供分享

npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip

• 生成 ZIP 文件，可在 Playground 中加载或附加到错误报告中。

5）使用 Xdebug 调试

• 使用 --xdebug 启动（或根据 CLI 版本使用 --enable-xdebug）以公开 IDE 密钥，然后将 VS Code/PhpStorm 连接到 CLI 输出中显示的主机／端口。
• 与 --auto-mount 配合使用可调试插件／主题。
• 检查清单：references/debugging.md

6）切换版本

• 使用 --wp= 固定 WP 版本（例如 6.9.0），并使用 --php= 测试兼容性。
• 如果功能依赖 Gutenberg trunk，优先使用最新 WP 版本并搭配可用的插件；Playground 镜像使用稳定版 WP 和捆绑的 Gutenberg。

7）仅限浏览器的工作流（无需 CLI）

• 使用 URL 片段或查询参数启动快速预览：
  • 片段：https://playground.wordpress.net/#<base64-or-json-blueprint>
  • 查询：https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>
• 使用在线 Blueprint Editor（playground.wordpress.net）编写 Blueprint，并借助架构说明；粘贴 JSON 后复制可分享的链接。

验证

• 确认挂载的代码已生效（插件已列出／启用；主题已选中）。
• 对于 Blueprint／快照，使用 --verbosity=debug 重新运行，以确认步骤已执行。
• 运行有针对性的冒烟测试（例如，如果已开放浏览器终端，可在 Playground shell 中运行 wp plugin list），或按 UI 点击路径操作。

故障模式／调试

• CLI 因 Node 版本报错退出：升级到 ≥ 20.18。
• 未应用挂载：检查路径，使用绝对路径，并添加 --verbosity=debug。
• Blueprint 无法读取本地资源：添加 --blueprint-may-read-adjacent-files。
• 端口已被占用：使用 --port=<free-port>。
• UI 缓慢／卡住：如果已启用 --experimental-multi-worker，请将其禁用；也可启用该选项，以提高 CPU 密集型运行的吞吐量。

升级处理

• 如果需要 PHP 扩展或原生数据库访问，Playground 可能不适用；请改用完整 WP 技术栈或 wp-env/Docker。
• 有关仅限浏览器的嵌入或 VS Code 扩展的具体信息，请参阅上游文档：https://wordpress.github.io/wordpress-playground/