wp-playground

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WordPress Playground

When to use

适用场景

Spin up a disposable WordPress to test a plugin/theme without full stack setup.
Run or iterate on Playground Blueprints (JSON) locally.
Build a reproducible snapshot of a site for sharing or CI.
Switch WP/PHP versions quickly to reproduce issues.
Debug plugin/theme code with Xdebug in an isolated Playground.

无需完整环境搭建，快速创建可丢弃的WordPress实例以测试插件/主题。
本地运行或迭代Playground Blueprints（JSON格式）。
构建可复现的站点快照用于分享或CI流程。
快速切换WP/PHP版本以复现问题。
在隔离的Playground环境中使用Xdebug调试插件/主题代码。

Inputs required

所需输入

Host machine readiness: Node.js ≥ 20.18,
```
npm
```
/
```
npx
```
available.
Project path to mount (
```
--auto-mount
```
or explicit mount mapping).
Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
Blueprint location/URL if running a blueprint.
Port preference if 9400 conflicts.
Whether Xdebug is needed.

主机环境准备：Node.js ≥ 20.18，且可使用
```
npm
```
/
```
npx
```
。
要挂载的项目路径（
```
--auto-mount
```
参数或显式挂载映射）。
所需的WP版本/PHP版本（可选；默认使用最新版WP和PHP 8.3）。
若运行蓝图，需提供蓝图文件路径/URL。
若端口9400冲突，需指定偏好端口。
是否需要Xdebug。

Procedure

操作步骤

0) Guardrails

0) 注意事项

Playground instances are ephemeral and SQLite-backed; never point at production data.
Confirm Node ≥ 20.18 (
```
node -v
```
) before running CLI.
If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.

Playground实例是临时的，基于SQLite；切勿指向生产数据。
运行CLI前确认Node版本≥20.18（执行
```
node -v
```
查看）。
若挂载本地代码，确保代码中不含敏感信息；Playground会将文件复制到内存文件系统中。

1) Quick local spin-up (auto-mount)

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

bash

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

Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
Add
```
--wp=<version>
```
/
```
--php=<version>
```
as needed.
For classic full installs already present, add
```
--skip-wordpress-setup
```
and mount the whole tree.

bash

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

默认在http://localhost:9400打开。自动检测插件/主题并完成安装。
可根据需要添加
```
--wp=<版本号>
```
/
```
--php=<版本号>
```
参数。
若已有完整的经典WordPress安装，可添加
```
--skip-wordpress-setup
```
参数并挂载整个目录树。

2) Manual mounts or multiple mounts

2) 手动挂载或多项目挂载

Use
```
--mount=/host/path:/vfs/path
```
(repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
Mount before install with
```
--mount-before-install
```
for bootstrapping installer flows.
Reference:
```
references/cli-commands.md
```

当自动挂载无法满足需求（如多插件、mu-plugins、自定义内容）时，使用
```
--mount=/主机路径:/vfs路径
```
参数（可重复使用）。
若要在安装前挂载以引导安装流程，使用
```
--mount-before-install
```
参数。
参考文档：
```
references/cli-commands.md
```

3) Run a Blueprint (no server needed)

3) 运行蓝图（无需服务器）

bash

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

Use for scripted setup/CI validation. Supports remote URLs and local files.
Allow bundled assets in local blueprints with
```
--blueprint-may-read-adjacent-files
```
when required.
See
```
references/blueprints.md
```
for structure and common flags.

bash

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

用于脚本化设置或CI验证。支持远程URL和本地文件。
若本地蓝图需要读取相邻文件中的捆绑资源，需添加
```
--blueprint-may-read-adjacent-files
```
参数。
蓝图结构及常用参数参考：
```
references/blueprints.md
```

4) Build a snapshot for sharing

4) 构建用于分享的站点快照

bash

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

Produces a ZIP you can load in Playground or attach to bug reports.

bash

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

生成可在Playground中加载或附加到Bug报告的ZIP文件。

5) Debugging with Xdebug

5) 使用Xdebug调试

Start with
```
--xdebug
```
(or
```
--enable-xdebug
```
depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
Combine with
```
--auto-mount
```
for plugin/theme debugging.
Checklist:
```
references/debugging.md
```

添加
```
--xdebug
```
参数（或根据CLI版本使用
```
--enable-xdebug
```
）启动，CLI输出会显示IDE密钥，随后将VS Code/PhpStorm连接到对应的主机/端口。
可结合
```
--auto-mount
```
参数调试插件/主题。
调试检查清单：
```
references/debugging.md
```

6) Version switching

6) 版本切换

Use
```
--wp=
```
to pin WP (e.g., 6.9.0) and
```
--php=
```
to test compatibility.
If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.

使用
```
--wp=
```
参数固定WP版本（例如6.9.0），使用
```
--php=
```
参数测试兼容性。
若功能依赖Gutenberg开发版，优先使用最新版WP加上对应插件（若有）；Playground镜像跟踪稳定版WP及捆绑的Gutenberg。

7) Browser-only workflows (no CLI)

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

Launch quick previews with URL fragments or query params:

Fragment:

https://playground.wordpress.net/#<base64-or-json-blueprint>

Query:

https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>

Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.

通过URL片段或查询参数启动快速预览：

片段方式：

https://playground.wordpress.net/#<base64或JSON格式的蓝图>

查询参数方式：

https://playground.wordpress.net/?blueprint-url=<公共URL或ZIP文件>

使用在线蓝图编辑器（playground.wordpress.net）编写蓝图，编辑器提供Schema提示；粘贴JSON后可复制可分享链接。

Verification

验证步骤

Verify mounted code is active (plugin listed/active; theme selected).
For blueprints/snapshots, re-run with
```
--verbosity=debug
```
to confirm steps executed.
Run targeted smoke (e.g.,
```
wp plugin list
```
inside Playground shell via browser terminal if exposed) or UI click-path.

验证挂载的代码已激活（插件已列出/启用，主题已选中）。
对于蓝图/快照，添加
```
--verbosity=debug
```
参数重新运行以确认步骤已执行。
运行针对性的冒烟测试（例如，若浏览器终端已开放，可在Playground shell中执行
```
wp plugin list
```
）或UI路径测试。

Failure modes / debugging

故障排查

CLI exits complaining about Node: upgrade to ≥ 20.18.
Mount not applied: check path, use absolute path, add
```
--verbosity=debug
```
.
Blueprint cannot read local assets: add
```
--blueprint-may-read-adjacent-files
```
.
Port already used:
```
--port=<free-port>
```
.
Slow/locked UI: disable
```
--experimental-multi-worker
```
if enabled; or enable it to improve throughput on CPU-bound runs.

CLI提示Node版本问题：升级Node.js至≥20.18。
挂载未生效：检查路径，使用绝对路径，添加
```
--verbosity=debug
```
参数查看详情。
蓝图无法读取本地资源：添加
```
--blueprint-may-read-adjacent-files
```
参数。
端口已被占用：使用
```
--port=<空闲端口>
```
参数指定端口。
UI缓慢/卡顿：若已启用
```
--experimental-multi-worker
```
则禁用；或启用该参数以提升CPU密集型任务的处理能力。

Escalation

替代方案

If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/

若需要PHP扩展或原生数据库访问，Playground可能不适用；可改用完整WP环境、wp-env或Docker。
若需仅浏览器嵌入或VS Code扩展相关细节，请参考上游文档：https://wordpress.github.io/wordpress-playground/