用途
wp-playground 技能用于 WordPress Playground 相关的工作流，帮助你在浏览器或本地通过 @wp-playground/cli 快速启动一次性的 WordPress 实例。典型用途包括：
- 在不搭建完整技术栈的情况下，启动一次性的 WordPress 来测试插件或主题。
- 在本地运行或迭代 Playground Blueprint（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。
快速本地启动（auto-mount）
cd <plugin-or-theme-root>
npx @wp-playground/cli@latest server --auto-mount
默认在 http://localhost:9400 打开，自动检测插件/主题并安装。可按需添加 --wp=<version> / --php=<version>。对于已存在的经典完整安装，可加 --skip-wordpress-setup 并挂载整个目录树。
手动挂载或多个挂载
当 auto-mount 不足时（多插件、mu-plugins、自定义内容），使用 --mount=/host/path:/vfs/path（可重复）。若要在安装前挂载以引导安装流程，使用 --mount-before-install。参考：references/cli-commands.md。
运行 Blueprint（无需服务器）
npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
用于脚本化设置/CI 验证，支持远程 URL 与本地文件。如需允许本地 blueprint 读取随附资源，使用 --blueprint-may-read-adjacent-files。结构见 references/blueprints.md。
构建用于分享的快照
npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
生成可在 Playground 中加载或附加到 bug 报告的 ZIP 文件。
使用 Xdebug 调试
使用 --xdebug（或依 CLI 版本为 --enable-xdebug）启动以暴露 IDE key，然后将 VS Code/PhpStorm 连接到 CLI 输出中显示的主机/端口。可与 --auto-mount 组合用于插件/主题调试。检查清单：references/debugging.md。
版本切换
用 --wp= 固定 WP 版本（如 6.9.0），用 --php= 测试兼容性。若功能依赖 Gutenberg trunk，优先使用最新 WP 版本加插件（如可用）；Playground 镜像跟踪稳定版 WP 及捆绑的 Gutenberg。
仅浏览器工作流（无 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）在 schema 帮助下编写 blueprint，粘贴 JSON 并复制可分享链接。
验证
- 验证挂载的代码已生效（插件已列出/激活；主题已选择）。
- 对 blueprint/快照，用
--verbosity=debug重跑以确认步骤执行。 - 运行针对性冒烟测试（例如通过浏览器终端在 Playground shell 内执行
wp plugin list，如暴露），或 UI 点击路径。
限制与失败模式
- Playground 实例是临时的、基于 SQLite；绝不指向生产数据。
- 运行 CLI 前确认 Node ≥ 20.18（node -v）。
- 若挂载本地代码，确保不含密钥；Playground 会把文件复制到内存 FS。
- 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/