blueprint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WordPress Playground Blueprints

WordPress Playground Blueprint 指南

Overview

概述

A Blueprint is a JSON file that declaratively configures a WordPress Playground instance — installing plugins/themes, setting options, running PHP/SQL, manipulating files, and more.

Core principle: Blueprints are trusted JSON-only declarations. No arbitrary JavaScript. They work on web, Node.js, and CLI.

Blueprint是一种JSON文件，用于声明式配置WordPress Playground实例——包括安装插件/主题、设置选项、运行PHP/SQL、操作文件等。

核心原则：Blueprint是仅受信任的JSON声明，不支持任意JavaScript。可在Web、Node.js和CLI环境中使用。

Quick Start Template

快速入门模板

json

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

json

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

Top-Level Properties

顶层属性

All optional. Only documented keys are allowed — the schema rejects unknown properties.

Property	Type	Notes
`$schema`	string	Always `"https://playground.wordpress.net/blueprint-schema.json"`
`landingPage`	string	Relative path, e.g. `/wp-admin/`
`meta`	object	`{ title, author, description?, categories? }` — title and author required
`preferredVersions`	object	`{ php, wp }` — both required when present
`features`	object	`{ networking?: boolean, intl?: boolean }` — only these two keys, nothing else. Networking defaults to `true`
`extraLibraries`	array	`["wp-cli"]` — auto-included when any `wp-cli` step is present
`constants`	object	Shorthand for `defineWpConfigConsts` . Values: string/boolean/number
`plugins`	array	Shorthand for `installPlugin` steps. Strings = wp.org slugs
`siteOptions`	object	Shorthand for `setSiteOptions`
`login`	boolean or object	`true` = login as admin. Object = `{ username?, password? }` (both default to `"admin"` / `"password"` )
`steps`	array	Main execution pipeline. Runs after shorthands

所有属性均为可选。仅允许使用文档中记录的键——Schema会拒绝未知属性。

属性	类型	说明
`$schema`	字符串	固定为 `"https://playground.wordpress.net/blueprint-schema.json"`
`landingPage`	字符串	相对路径，例如 `/wp-admin/`
`meta`	对象	`{ title, author, description?, categories? }` —— title和author为必填项
`preferredVersions`	对象	`{ php, wp }` —— 存在时两者均为必填
`features`	对象	`{ networking?: boolean, intl?: boolean }` —— 仅支持这两个键，无其他选项。networking默认值为 `true`
`extraLibraries`	数组	`["wp-cli"]` —— 当存在任意 `wp-cli` 步骤时会自动包含
`constants`	对象	`defineWpConfigConsts` 的简写形式。值类型：字符串/布尔值/数字
`plugins`	数组	`installPlugin` 步骤的简写形式。字符串为wp.org的插件别名
`siteOptions`	对象	`setSiteOptions` 的简写形式
`login`	布尔值或对象	`true` 表示以管理员身份登录。对象格式为 `{ username?, password? }` （默认值均为 `"admin"` / `"password"` ）
`steps`	数组	主执行流程。在简写配置之后运行

preferredVersions Values

preferredVersions 取值说明

php: Major.minor only (e.g.
```
"8.3"
```
,
```
"7.4"
```
), or
```
"latest"
```
. Patch versions like
```
"7.4.1"
```
are invalid. Check the schema for currently supported versions.
wp: Recent major versions (e.g.
```
"6.7"
```
,
```
"6.8"
```
),
```
"latest"
```
,
```
"nightly"
```
,
```
"beta"
```
, or a URL to a custom zip. Check the schema for the full list.

php：仅支持主版本.次版本格式（例如
```
"8.3"
```
,
```
"7.4"
```
），或
```
"latest"
```
。类似
```
"7.4.1"
```
的补丁版本无效。请查看Schema获取当前支持的版本列表。
wp：支持近期主版本（例如
```
"6.7"
```
,
```
"6.8"
```
）、
```
"latest"
```
、
```
"nightly"
```
、
```
"beta"
```
，或自定义压缩包的URL。请查看Schema获取完整列表。

Shorthands vs Steps

简写配置 vs 步骤

Shorthands (

login

plugins

siteOptions

constants

) are expanded and prepended to

steps

in an unspecified order. Use explicit steps when execution order matters.

简写配置（

login

plugins

siteOptions

constants

）会被展开并前置到

steps

中，顺序不固定。当执行顺序重要时，请使用显式步骤。

Resource References

资源引用

Resources tell Playground where to find files. Used by

installPlugin

installTheme

writeFile

writeFiles

importWxr

, etc.

Resource Type	Required Fields	Example
`wordpress.org/plugins`	`slug`	`{ "resource": "wordpress.org/plugins", "slug": "woocommerce" }`
`wordpress.org/themes`	`slug`	`{ "resource": "wordpress.org/themes", "slug": "astra" }`
`url`	`url`	`{ "resource": "url", "url": "https://example.com/plugin.zip" }`
`git:directory`	`url` , `ref`	See below
`literal`	`name` , `contents`	`{ "resource": "literal", "name": "file.txt", "contents": "hello" }`
`literal:directory`	`name` , `files`	See below
`bundled`	`path`	References a file within a blueprint bundle (e.g. `{ "resource": "bundled", "path": "/plugin.zip" }` )
`zip`	`inner`	Wraps another resource in a ZIP — use when a step expects a zip but your source isn't one (e.g. wrapping a `url` resource pointing to a raw directory)

资源用于告知Playground文件的位置。适用于

installPlugin

、

installTheme

、

writeFile

、

writeFiles

、

importWxr

等步骤。

资源类型	必填字段	示例
`wordpress.org/plugins`	`slug`	`{ "resource": "wordpress.org/plugins", "slug": "woocommerce" }`
`wordpress.org/themes`	`slug`	`{ "resource": "wordpress.org/themes", "slug": "astra" }`
`url`	`url`	`{ "resource": "url", "url": "https://example.com/plugin.zip" }`
`git:directory`	`url` , `ref`	见下文
`literal`	`name` , `contents`	`{ "resource": "literal", "name": "file.txt", "contents": "hello" }`
`literal:directory`	`name` , `files`	见下文
`bundled`	`path`	引用Blueprint包内的文件（例如 `{ "resource": "bundled", "path": "/plugin.zip" }` ）
`zip`	`inner`	将其他资源包装为ZIP格式——当步骤需要ZIP文件但源资源不是ZIP时使用（例如包装指向原始目录的 `url` 资源）

git:directory — Installing from GitHub

git:directory —— 从GitHub安装

json

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}

When using a branch or tag name for
```
ref
```
, you must set
```
refType
```
(
```
"branch"
```
|
```
"tag"
```
|
```
"commit"
```
|
```
"refname"
```
). Without it, only
```
"HEAD"
```
resolves reliably.
```
path
```
selects a subdirectory (defaults to repo root).

json

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}

当使用分支或标签名称作为
```
ref
```
时，必须设置
```
refType
```
（
```
"branch"
```
|
```
"tag"
```
|
```
"commit"
```
|
```
"refname"
```
）。如果不设置，仅
```
"HEAD"
```
能可靠解析。
```
path
```
用于选择子目录（默认为仓库根目录）。

literal:directory — Inline File Trees

literal:directory —— 内联文件树

json

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}

```
files
```
uses nested objects for subdirectories — keys are filenames or directory names, values are plain strings (file content) or objects (subdirectories). Never use resource references as values.
Do NOT use path separators in keys (e.g.
```
"includes/helper.php"
```
is wrong — use a nested
```
"includes": { "helper.php": "..." }
```
object).

json

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}

```
files
```
使用嵌套对象表示子目录——键为文件名或目录名，值为纯字符串（文件内容）或对象（子目录）。请勿将资源引用作为值。
请勿在键中使用路径分隔符（例如
```
"includes/helper.php"
```
是错误的——应使用嵌套的
```
"includes": { "helper.php": "..." }
```
对象）。

Steps Reference

步骤参考

Every step requires

"step": "<name>"

. Any step can optionally include

"progress": { "weight": 1, "caption": "Installing..." }

for UI feedback.

每个步骤都需要

"step": "<name>"

。任意步骤都可选择性包含

"progress": { "weight": 1, "caption": "Installing..." }

以提供UI反馈。

Plugin & Theme Installation

插件与主题安装

json

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}

json

{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}

Use

pluginData

themeData

— NOT the deprecated

pluginZipFile

themeZipFile

```
pluginData
```
/
```
themeData
```
accept any FileReference or DirectoryReference — a zip URL, a
```
wordpress.org/plugins
```
slug, a
```
git:directory
```
, or a
```
literal:directory
```
(no
```
zip
```
wrapper needed).

options.activate

controls activation. No need for a separate

activatePlugin

activateTheme

step when using

installPlugin

installTheme

ifAlreadyInstalled

"overwrite"

"skip"

"error"

json

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}

json

{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}

使用

pluginData

themeData

——不要使用已弃用的

pluginZipFile

themeZipFile

。

```
pluginData
```
/
```
themeData
```
支持任意FileReference或DirectoryReference——包括ZIP URL、
```
wordpress.org/plugins
```
别名、
```
git:directory
```
或
```
literal:directory
```
（无需
```
zip
```
包装）。

options.activate

控制激活状态。使用

installPlugin

installTheme

时，无需单独的

activatePlugin

activateTheme

步骤。

ifAlreadyInstalled

可选值：

"overwrite"

"skip"

"error"

Activation (standalone)

单独激活

Only needed for plugins/themes already on disk (e.g. after

writeFile

writeFiles

json

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

json

{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

仅适用于已存在于磁盘中的插件/主题（例如

writeFile

writeFiles

之后）：

json

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

json

{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

File Operations

文件操作

json

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data

accepts a plain string (as shown above) or a resource reference (e.g.

{ "resource": "url", "url": "https://..." }

json

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFiles
requires a DirectoryReference (

literal:directory

git:directory

) as

filesTree

— not a plain object.

Other file operations:

mkdir

cp

mv

rm

rmdir

unzip

json

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data

支持纯字符串（如上所示）或资源引用（例如

{ "resource": "url", "url": "https://..." }

）。

json

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFiles
要求
filesTree
为DirectoryReference（

literal:directory

或

git:directory

）——不能是纯对象。

其他文件操作步骤：

mkdir

cp

mv

rm

rmdir

unzip

。

Running Code

运行代码

runPHP:

json

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

GOTCHA: You must

require '/wordpress/wp-load.php';

to use any WordPress functions.

wp-cli:

json

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

The step name is

wp-cli

(with hyphen), NOT

cli

wpcli

runSql:

json

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

runPHP：

json

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

注意： 若要使用WordPress函数，必须

require '/wordpress/wp-load.php';

。

wp-cli：

json

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

步骤名称为

wp-cli

（含连字符），而非

cli

或

wpcli

。

runSql：

json

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

Site Configuration

站点配置

json

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }

json

{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }

json

{ "step": "setSiteLanguage", "language": "en_US" }

json

{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

json

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }

json

{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }

json

{ "step": "setSiteLanguage", "language": "en_US" }

json

{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

Other Steps

其他步骤

Step	Key Properties
`login`	`username?` , `password?` (default `"admin"` / `"password"` )
`enableMultisite`	(no required props)
`importWxr`	`file` (FileReference)
`importThemeStarterContent`	`themeSlug?`
`importWordPressFiles`	`wordPressFilesZip` , `pathInZip?` — imports a full WordPress directory from a zip
`request`	`request: { url, method?, headers?, body? }`
`updateUserMeta`	`userId` , `meta`
`runWpInstallationWizard`	`options?` — runs the WP install wizard with given options
`resetData`	(no props)

步骤	关键属性
`login`	`username?` , `password?` （默认值 `"admin"` / `"password"` ）
`enableMultisite`	无必填属性
`importWxr`	`file` （FileReference）
`importThemeStarterContent`	`themeSlug?`
`importWordPressFiles`	`wordPressFilesZip` , `pathInZip?` —— 从ZIP文件导入完整WordPress目录
`request`	`request: { url, method?, headers?, body? }`
`updateUserMeta`	`userId` , `meta`
`runWpInstallationWizard`	`options?` —— 使用指定选项运行WordPress安装向导
`resetData`	无属性

Common Patterns

常见模式

Inline mu-plugin (quick custom code)

内联mu-plugin（快速自定义代码）

json

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins load automatically — no activation needed, no require wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

json

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins会自动加载——无需激活，无需引入wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

Inline plugin with multiple files

包含多文件的内联插件

json

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

Then activate it with a separate step:

json

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

json

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

随后通过单独步骤激活：

json

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

Plugin from a GitHub branch

从GitHub分支安装插件

json

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

json

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

Common Mistakes

常见错误

Mistake	Correct
`pluginZipFile` / `themeZipFile`	`pluginData` / `themeData`
`"step": "cli"`	`"step": "wp-cli"`
Flat object as `writeFiles.filesTree`	Must be a `literal:directory` or `git:directory` resource
Path separators in `files` keys	Use nested objects for subdirectories
`runPHP` without `wp-load.php`	Always `require '/wordpress/wp-load.php';` for WP functions
Invented top-level keys	Only documented keys work — schema rejects unknown properties
Inventing proxy URLs for GitHub	Use `git:directory` resource type
Omitting `refType` with branch/tag `ref`	Required — only `"HEAD"` works without it
Resource references in `literal:directory` `files` values	Values must be plain strings (content) or objects (subdirectories) — never resource refs
`features.debug` or other invented feature keys	`features` only supports `networking` and `intl` — use `constants: { "WP_DEBUG": true }` for debug mode
`require wp-load.php` in mu-plugin code	Only needed in `runPHP` steps — mu-plugins already run within WordPress
Schema URL with `.org` domain	Must be `playground.wordpress.net` , not `playground.wordpress.org`

错误用法	正确用法
`pluginZipFile` / `themeZipFile`	`pluginData` / `themeData`
`"step": "cli"`	`"step": "wp-cli"`
将纯对象作为 `writeFiles.filesTree`	必须使用 `literal:directory` 或 `git:directory` 资源
在 `files` 键中使用路径分隔符	使用嵌套对象表示子目录
`runPHP` 中未引入 `wp-load.php`	使用WordPress函数时必须 `require '/wordpress/wp-load.php';`
自定义顶层键	仅支持文档中记录的键——Schema会拒绝未知属性
为GitHub自定义代理URL	使用 `git:directory` 资源类型
使用分支/标签 `ref` 时省略 `refType`	必须设置——仅 `"HEAD"` 无需设置即可可靠解析
在 `literal:directory` 的 `files` 值中使用资源引用	值必须为纯字符串（内容）或对象（子目录）——不能是资源引用
`features.debug` 或其他自定义功能键	`features` 仅支持 `networking` 和 `intl` ——调试模式请使用 `constants: { "WP_DEBUG": true }`
在mu-plugin代码中引入 `wp-load.php`	仅在 `runPHP` 步骤中需要——mu-plugin已在WordPress环境中运行
使用 `.org` 域名的Schema URL	必须使用 `playground.wordpress.net` ，而非 `playground.wordpress.org`

Full Reference

完整参考

This skill covers the most common steps and patterns. For the complete API, see:

Blueprint docs: https://wordpress.github.io/wordpress-playground/blueprints
JSON schema: https://playground.wordpress.net/blueprint-schema.json

Additional steps not covered above:

runPHPWithOptions

(run PHP with custom

ini

settings),

runWpInstallationWizard

, and resource types

vfs

and

bundled

(for advanced embedding scenarios).

本指南涵盖了最常用的步骤和模式。如需完整API，请查看：

Blueprint文档：https://wordpress.github.io/wordpress-playground/blueprints
JSON Schema：https://playground.wordpress.net/blueprint-schema.json

本指南未涵盖的其他步骤：

runPHPWithOptions

（使用自定义

ini

设置运行PHP）、

runWpInstallationWizard

，以及资源类型

vfs

和

bundled

（用于高级嵌入场景）。

Blueprint Bundles

Blueprint 包

Bundles are self-contained packages that include a

blueprint.json

along with all the resources it references (plugins, themes, WXR files, etc.). Instead of hosting assets externally, bundle them alongside the blueprint.

包是自包含的套件，包含

blueprint.json

及其引用的所有资源（插件、主题、WXR文件等）。无需在外部托管资源，可将它们与Blueprint打包在一起。

Bundle Structure

包结构

my-bundle/
├── blueprint.json          ← must be at the root
├── my-plugin.zip           ← zipped plugin directory
├── theme.zip
└── content/
    └── sample-content.wxr

Plugins and themes must be zipped before bundling —

installPlugin

expects a zip, not a raw directory. To create the zip from a plugin directory:

bash

cd my-bundle
zip -r my-plugin.zip my-plugin/

my-bundle/
├── blueprint.json          ← 必须位于根目录
├── my-plugin.zip           ← 插件目录的压缩包
├── theme.zip
└── content/
    └── sample-content.wxr

插件和主题在打包前必须压缩——

installPlugin

要求ZIP格式，而非原始目录。从插件目录创建ZIP的命令：

bash

cd my-bundle
zip -r my-plugin.zip my-plugin/

Referencing Bundled Resources

引用包内资源

Use the

bundled

resource type to reference files within the bundle:

json

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "bundled",
    "path": "/my-plugin.zip"
  },
  "options": { "activate": true }
}

json

{
  "step": "importWxr",
  "file": {
    "resource": "bundled",
    "path": "/content/sample-content.wxr"
  }
}

使用

bundled

资源类型引用包内的文件：

json

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "bundled",
    "path": "/my-plugin.zip"
  },
  "options": { "activate": true }
}

json

{
  "step": "importWxr",
  "file": {
    "resource": "bundled",
    "path": "/content/sample-content.wxr"
  }
}

Creating a Bundle Step by Step

逐步创建包

Create the bundle directory and add
```
blueprint.json
```
at its root.
Write your plugin/theme source files in a subdirectory (e.g.
```
my-plugin/my-plugin.php
```
).
Zip the plugin directory:
```
zip -r my-plugin.zip my-plugin/
```

Reference it in

blueprint.json

using

{ "resource": "bundled", "path": "/my-plugin.zip" }

Full example — a bundle that installs a custom plugin:

dashboard-widget-bundle/
├── blueprint.json
├── dashboard-widget.zip        ← zip of dashboard-widget/
└── dashboard-widget/           ← plugin source (kept for editing)
    └── dashboard-widget.php

json

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "bundled", "path": "/dashboard-widget.zip" },
      "options": { "activate": true }
    }
  ]
}

创建包目录，并在根目录添加
```
blueprint.json
```
。
在子目录中编写插件/主题源文件（例如
```
my-plugin/my-plugin.php
```
）。
压缩插件目录：
```
zip -r my-plugin.zip my-plugin/
```

在

blueprint.json

中使用

{ "resource": "bundled", "path": "/my-plugin.zip" }

引用该压缩包。

完整示例——安装自定义插件的包：

dashboard-widget-bundle/
├── blueprint.json
├── dashboard-widget.zip        ← dashboard-widget/目录的压缩包
└── dashboard-widget/           ← 插件源文件（用于编辑）
    └── dashboard-widget.php

json

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "bundled", "path": "/dashboard-widget.zip" },
      "options": { "activate": true }
    }
  ]
}

Distribution Formats

分发格式

Format	How to use
ZIP file (remote)	Website: `https://playground.wordpress.net/?blueprint-url=https://example.com/bundle.zip`
ZIP file (local)	CLI: `npx @wp-playground/cli server --blueprint=./bundle.zip`
Local directory	CLI: `npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files`
Git repository directory	Point `blueprint-url` at a repo directory containing `blueprint.json`

GOTCHA: Local directory bundles always need

--blueprint-may-read-adjacent-files

for the CLI to read bundled resources. Without it, any

"resource": "bundled"

reference will fail with a "File not found" error. ZIP bundles don't need this flag — all files are self-contained inside the archive.

格式	使用方式
ZIP文件（远程）	网页端： `https://playground.wordpress.net/?blueprint-url=https://example.com/bundle.zip`
ZIP文件（本地）	CLI： `npx @wp-playground/cli server --blueprint=./bundle.zip`
本地目录	CLI： `npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files`
Git仓库目录	将 `blueprint-url` 指向包含 `blueprint.json` 的仓库目录

注意： 本地目录包在CLI中必须添加

--blueprint-may-read-adjacent-files

参数才能读取包内资源。如果不添加，所有

"resource": "bundled"

引用都会因“文件未找到”错误而失败。ZIP包无需此参数——所有文件都已包含在归档文件中。

Testing Blueprints

测试Blueprint

Inline Blueprints (quick test, no bundles)

内联Blueprint（快速测试，无需打包）

Minify the blueprint JSON (no extra whitespace), prepend

https://playground.wordpress.net/#

, and open the URL in a browser:

https://playground.wordpress.net/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}

Very large blueprints may exceed browser URL length limits; use the CLI instead.

压缩Blueprint JSON（无多余空格），在前面添加

https://playground.wordpress.net/#

，然后在浏览器中打开该URL：

https://playground.wordpress.net/#{"$schema":"https://playground.wordpress.net/blueprint-schema.json","preferredVersions":{"php":"8.3","wp":"latest"},"steps":[{"step":"login"}]}

过大的Blueprint可能会超出浏览器URL长度限制；此时请使用CLI。

Local CLI Testing

本地CLI测试

Interactive server (keeps running, opens in browser):

bash

undefined

交互式服务器（持续运行，在浏览器中打开）：

bash

undefined

Directory bundle — requires --blueprint-may-read-adjacent-files

目录包——需要添加--blueprint-may-read-adjacent-files参数

npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

ZIP bundle — self-contained, no extra flags needed

ZIP包——自包含，无需额外参数

npx @wp-playground/cli server --blueprint=./bundle.zip


**Headless validation** (runs blueprint and exits):
```bash
npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

npx @wp-playground/cli server --blueprint=./bundle.zip


**无头验证**（运行Blueprint后退出）：
```bash
npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

Testing with the wordpress-playground-server Skill

使用wordpress-playground-server技能测试

Use the

wordpress-playground-server

skill to start a local Playground instance with

--blueprint /path/to/blueprint.json

, then verify the expected state with Playwright MCP. For directory bundles, pass

--blueprint-may-read-adjacent-files

as an extra argument.

使用

wordpress-playground-server

技能启动本地Playground实例，参数为

--blueprint /path/to/blueprint.json

，然后使用Playwright MCP验证预期状态。对于目录包，需额外传递

--blueprint-may-read-adjacent-files

参数。