name: wp-playground
description: “用于WordPress Playground工作流：在浏览器或通过@wp-playground/cli本地快速创建一次性WP实例（server、run-blueprint、build-snapshot），自动挂载插件/主题，切换WP/PHP版本，使用蓝图，以及调试（Xdebug）。”
compatibility: “目标环境WordPress 6.9+（PHP 7.2.24+）。Playground CLI需要Node.js 20.18+；在WebAssembly中使用SQLite运行WP。”
WordPress Playground
使用场景
- 快速启动一个一次性WordPress实例来测试插件/主题，无需完整环境搭建。
- 本地运行或迭代Playground蓝图（JSON）。
- 构建可复现的站点快照用于分享或CI。
- 快速切换WP/PHP版本以复现问题。
- 在隔离的Playground环境中使用Xdebug调试插件/主题代码。
所需输入
- 主机准备：Node.js ≥ 20.18，
npm/npx可用。
- 要挂载的项目路径（
--auto-mount或显式挂载映射）。
- 期望的WP版本/PHP版本（可选；默认为最新WP，PHP 8.3）。
- 蓝图文件位置/URL（如果运行蓝图）。
- 端口偏好（如果9400冲突）。
- 是否需要Xdebug。
操作流程
0) 注意事项
- Playground实例是临时的且基于SQLite；切勿指向生产数据。
- 运行CLI前确认Node ≥ 20.18（
node -v）。
- 如果挂载本地代码，确保其中不包含敏感信息；Playground会将文件复制到内存文件系统中。
1) 快速本地启动（自动挂载）
cd <插件或主题根目录>
npx @wp-playground/cli@latest server --auto-mount
- 默认在 http://localhost:9400 打开。自动检测插件/主题并安装。
- 根据需要添加
--wp=<版本> / --php=<版本>。
- 对于已存在的经典完整安装，添加
--skip-wordpress-setup 并挂载整个目录树。
2) 手动挂载或多挂载点
- 当自动挂载不满足需求时（多插件、mu-plugins、自定义内容），使用
--mount=/主机路径:/虚拟文件系统路径（可重复）。
- 使用
--mount-before-install 在安装前挂载，用于引导安装流程。
- 参考：
references/cli-commands.md
3) 运行蓝图（无需服务器）
npx @wp-playground/cli@latest run-blueprint --blueprint=<文件或URL>
- 用于脚本化设置/CI验证。支持远程URL和本地文件。
- 当需要时，使用
--blueprint-may-read-adjacent-files 允许本地蓝图读取相邻的资产文件。
- 有关结构和常用标志，请参阅
references/blueprints.md。
4) 构建快照用于分享
npx @wp-playground/cli@latest build-snapshot --blueprint=<文件> --outfile=./site.zip
- 生成一个ZIP文件，可在Playground中加载或附加到错误报告中。
5) 使用Xdebug调试
- 使用
--xdebug（或根据CLI版本使用 --enable-xdebug）启动以暴露IDE密钥，然后按照CLI输出中显示的主机/端口连接VS Code/PhpStorm。
- 结合
--auto-mount 进行插件/主题调试。
- 清单：
references/debugging.md
6) 版本切换
- 使用
--wp= 固定WP版本（例如，6.9.0），使用 --php= 测试兼容性。
- 如果功能依赖于Gutenberg主干版本，优先选择最新的WP版本加上插件（如果可用）；Playground镜像跟踪稳定的WP版本以及捆绑的Gutenberg。
7) 纯浏览器工作流（无需CLI）
- 使用URL片段或查询参数启动快速预览：
- 片段：
https://playground.wordpress.net/#<base64或json蓝图>
- 查询：
https://playground.wordpress.net/?blueprint-url=<公开URL或zip>
- 使用实时蓝图编辑器（playground.wordpress.net）借助模式帮助编写蓝图；粘贴JSON并复制可分享的链接。
验证
- 验证挂载的代码已激活（插件已列出/激活；主题已选择）。
- 对于蓝图/快照，使用
--verbosity=debug 重新运行以确认步骤已执行。
- 运行针对性冒烟测试（例如，通过浏览器终端在Playground shell内运行
wp plugin list）或UI点击路径。
故障模式 / 调试
- CLI退出并抱怨Node版本：升级到 ≥ 20.18。
- 挂载未生效：检查路径，使用绝对路径，添加
--verbosity=debug。
- 蓝图无法读取本地资产：添加
--blueprint-may-read-adjacent-files。
- 端口已被占用：
--port=<空闲端口>。
- UI缓慢/卡顿：如果启用了
--experimental-multi-worker 则禁用它；或者启用它以改善CPU密集型运行的吞吐量。
升级/替代方案