blueprint

WordPress Playground 蓝图

概述

蓝图是一个 JSON 文件，用声明式方式配置 WordPress Playground 实例，可用于安装插件/主题、设置选项、运行 PHP/SQL、操作文件等。

**核心原则：**蓝图是可信的纯 JSON 声明，不包含任意 JavaScript。可在 Web、Node.js 和 CLI 上运行。

快速入门模板

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

顶层属性

所有属性均为可选项。只允许使用文档中列出的键——架构会拒绝未知属性。

属性	类型	说明
$schema	字符串	始终为 "https://playground.wordpress.net/blueprint-schema.json"
landingPage	字符串	相对路径，例如 /wp-admin/
description	字符串	已弃用的可选顶层描述。新蓝图请优先使用 meta.description
meta	对象	{ title, author, description?, categories? } — title 和 author 为必填项
preferredVersions	对象	{ php, wp } — 存在时两者均为必填项
features	对象	{ networking?: boolean, intl?: boolean } — 仅允许这两个键，不可包含其他键。networking 默认为 true
phpExtensionBundles	任意	已弃用/不再使用；架构不限制其值，并建议从蓝图中移除
extraLibraries	数组	["wp-cli"] — 存在任何 wp-cli 步骤时自动包含
constants	对象	defineWpConfigConsts 的简写。值可为字符串/布尔值/数字
plugins	数组	installPlugin 步骤的简写。字符串表示 wp.org slug
siteOptions	对象	setSiteOptions 的简写
login	布尔值或对象	true = 以管理员身份登录。对象 = { username?, password? }（两者默认为 "admin"/"password"）
steps	数组	主执行流程。在简写项之后运行

preferredVersions 的值

• **php：**仅限主版本号和次版本号："7.4"、"8.0"、"8.1"、"8.2"、"8.3"、"8.4"、"8.5" 或 "latest"。补丁版本（如 "7.4.1"）无效。请查看架构，了解当前支持的版本。
• **wp：**近期主版本、"latest"、"beta"、"nightly"/"trunk"，或自定义 zip 的 URL。架构也接受仅用于 PHP 的 Playground 所需的 false；不要将 wp: false 与仅适用于 WordPress 的字段（如 plugins、siteOptions、login 或仅适用于 WordPress 的步骤）同时使用。

简写项与步骤

简写项（login、plugins、siteOptions、constants）会按未指定的顺序展开并添加到 steps 前面。执行顺序很重要时，请使用明确的步骤。

资源引用

资源用于告知 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	引用蓝图包中的文件（例如 { "resource": "bundled", "path": "/plugin.zip" }）
zip	inner	将另一个资源包装为 ZIP — 当某个步骤要求 ZIP，但源资源不是 ZIP 时使用（例如将指向原始目录的 url 资源包装为 ZIP）

git:directory — 从 GitHub 安装

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

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

literal:directory — 内联文件树

{
  "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": "..." } 对象）。

步骤参考

每个步骤都需要 "step": "<name>"。任何步骤都可以选择性地包含 "progress": { "weight": 1, "caption": "Installing..." }，用于提供 UI 反馈。

插件和主题安装

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

{
  "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 slug、git:directory 或 literal:directory（无需 zip 包装）。
• options.activate 控制是否激活。使用 installPlugin / installTheme 时，无需单独添加 activatePlugin / activateTheme 步骤。
• ifAlreadyInstalled："overwrite" | "skip" | "error"

激活（独立步骤）

仅适用于已在磁盘上的插件/主题（例如，在 writeFile / writeFiles 之后）：

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

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

文件操作

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

data 接受纯字符串（如上所示）或资源引用（例如 { "resource": "url", "url": "https://..." }）。

{
  "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。

运行代码

runPHP：

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

**注意：**要使用任何 WordPress 函数，必须执行 require '/wordpress/wp-load.php';。

wp-cli：

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

步骤名称是 wp-cli（带连字符），而不是 cli 或 wpcli。

runSql：

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

站点配置

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

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

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

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

其他步骤

步骤	关键属性
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?——使用给定选项运行 WP 安装向导
resetData	（无属性）

常见模式

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

{
  "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');"
}

包含多个文件的内联插件

{
  "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"
      }
    }
  }
}

然后通过单独的步骤激活它：

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

来自 GitHub 分支的插件

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

常见错误

错误	正确写法
pluginZipFile / themeZipFile	pluginData / themeData
"step": "cli"	"step": "wp-cli"
将扁平对象用作 writeFiles.filesTree	必须使用 literal:directory 或 git:directory 资源
在 files 键中使用路径分隔符	使用嵌套对象表示子目录
runPHP 中没有 wp-load.php	使用 WP 函数时，始终执行 require '/wordpress/wp-load.php';
自行编造顶层键	仅文档中列出的键有效——架构会拒绝未知属性
为 GitHub 编造代理 URL	使用 git:directory 资源类型
在分支/标签 ref 中省略 refType	必需——不指定时仅 "HEAD" 有效
在 literal:directory 的 files 值中使用资源引用	值必须是纯字符串（内容）或对象（子目录）——切勿使用资源引用
features.debug 或其他编造的功能键	features 仅支持 networking 和 intl——使用 constants: { "WP_DEBUG": true } 启用调试模式
在 mu-plugin 代码中使用 require wp-load.php	仅 runPHP 步骤需要——mu-plugin 已在 WordPress 中运行
架构 URL 使用 .org 域名	必须使用 playground.wordpress.net，而不是 playground.wordpress.org

完整参考

此技能涵盖最常见的步骤和模式。完整 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 Bundle

Bundle 是自包含的软件包，其中包含 blueprint.json 以及它引用的所有资源（插件、主题、WXR 文件等）。不要将资源托管在外部，而是将它们与 Blueprint 放在一起。

Bundle 结构

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

插件和主题必须先压缩成 ZIP 文件才能打包——installPlugin 需要的是 ZIP 文件，而不是原始目录。要从插件目录创建 ZIP 文件：

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

引用 Bundle 资源

使用 bundled 资源类型来引用 Bundle 中的文件：

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

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

逐步创建 Bundle

1. 创建 Bundle 目录，并在其根目录下添加 blueprint.json。
2. 在子目录中编写插件／主题源文件（例如 my-plugin/my-plugin.php）。
3. 将插件目录压缩成 ZIP 文件：zip -r my-plugin.zip my-plugin/
4. 在 blueprint.json 中使用 { "resource": "bundled", "path": "/my-plugin.zip" } 引用它。

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

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

{
  "$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 }
    }
  ]
}

分发格式

格式	使用方法
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 的仓库目录

注意： 本地目录 Bundle 始终需要 --blueprint-may-read-adjacent-files，CLI 才能读取打包的资源。若不添加此参数，任何 "resource": "bundled" 引用都会因“File not found”错误而失败。ZIP Bundle 不需要此参数——所有文件都自包含在压缩包中。

测试 Blueprint

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

精简 Blueprint JSON（不保留额外空白字符），使用 encodeURIComponent() 编码一次，在前面加上 https://playground.wordpress.net/#，然后在浏览器中打开此 URL：

https://playground.wordpress.net/#%7B%22%24schema%22%3A%22https%3A%2F%2Fplayground.wordpress.net%2Fblueprint-schema.json%22%2C%22preferredVersions%22%3A%7B%22php%22%3A%228.3%22%2C%22wp%22%3A%22latest%22%7D%2C%22steps%22%3A%5B%7B%22step%22%3A%22login%22%7D%5D%7D

非常大的 Blueprint 可能会超出浏览器的 URL 长度限制；请改用 CLI 或托管的 Blueprint URL。有关分享链接的详情，请参阅 wp-playground/references/website.md。

本地 CLI 测试

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

# Directory bundle — requires --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
npx @wp-playground/cli server --blueprint=./bundle.zip

无头验证（运行 Blueprint 后退出）：

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

使用 WordPress Playground 测试

使用 wp-playground 技能进行本地或浏览器测试。进行 CLI 测试时，请遵循 wp-playground/references/cli.md 并使用 --blueprint=<path-or-url>；对于目录 Bundle，请传入 --blueprint-may-read-adjacent-files。