blueprint

WordPress Playground Blueprints

概观 (Overview)

Blueprint 是一种 JSON 档案，可以宣告式地设定 WordPress Playground 实例 — 例如安装外挂/主题、设定选项、执行 PHP/SQL、操作档案等。

核心原则： Blueprint 是可信且纯 JSON 的宣告，不支援任意 JavaScript。可完美运作于网页、Node.js 及 CLI 环境。

快速上手范本 (Quick Start Template)

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

最上层属性 (Top-Level Properties)

所有属性皆为选填。仅允许文档中明确记载的键值 — Schema 会拒绝任何未知的属性。

属性	型别	备注
$schema	string	固定为 "https://playground.wordpress.net/blueprint-schema.json"
landingPage	string	相对路径，例如 /wp-admin/
description	string	已废弃的选填最上层描述。新建立 Blueprint 请优先使用 meta.description
meta	object	{ title, author, description?, categories? } — title 与 author 为必填
preferredVersions	object	{ php, wp } — 当存在此属性时，两者皆为必填
features	object	{ networking?: boolean, intl?: boolean } — 仅支援这两个键值，无其他。networking 预设为 true
phpExtensionBundles	any	已废弃/不再使用；Schema 未对其值作限制，建议从 Blueprint 中移除
extraLibraries	array	["wp-cli"] — 当存在任何 wp-cli 步骤时会自动引入
constants	object	defineWpConfigConsts 的简写。可填入的值：字串/布林值/数字
plugins	array	installPlugin 步骤的简写。字串表示 wp.org 的 slug
siteOptions	object	setSiteOptions 的简写
login	boolean 或 object	true = 以管理员身份登入。物件 = { username?, password? }（两者预设皆为 "admin"/"password"）
steps	array	主执行管线。会在所有简写步骤后执行

preferredVersions 可填入的值

• php: 仅限 Major.minor 格式："7.4"、"8.0"、"8.1"、"8.2"、"8.3"、"8.4"、"8.5" 或 "latest"。包含修订版本（Patch）的格式如 "7.4.1" 皆为无效。请参考 Schema 确认目前支援的版本。
• wp: 近期的主要版本、"latest"、"beta"、"nightly"/"trunk"，或指向自订 ZIP 的 URL。Schema 也接受 false 以用于纯 PHP 的 Playground 环境；请勿将 wp: false 与 WordPress 专属栏位（如 plugins、siteOptions、login 或 WordPress 专属步骤）混用。

简写 (Shorthands) vs 步骤 (Steps)

简写（login、plugins、siteOptions、constants）会以未指定顺序展开并插入至 steps 的最前方。若执行顺序相当关键，请务必使用明确的 steps 步骤。

资源参考 (Resource References)

资源（Resource）用来告知 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 bundle 内部的档案（例如 { "resource": "bundled", "path": "/plugin.zip" }）
zip	inner	将另一个资源包覆为 ZIP — 当步骤需要 zip 格式但你的来源不是 zip 时使用（例如包覆指向原始目录的 url 资源）

git:directory — 从 GitHub 安装

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

• 当使用分支（branch）或标籤（tag）名称作为 ref 时，必须设定 refType（"branch" | "tag" | "commit" | "refname"）。若未设定，仅有 "HEAD" 能稳定解析。
• path 用来指定子目录（预设为储存库根目录）。

literal:directory — 行内档案树 (Inline File Trees)

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

• files 针对子目录使用嵌套物件 — 键（key）为档名或目录名，值（value）为纯字串（档案内容）或物件（子目录）。绝对不要使用资源参考作为值。
• 请勿在键中使用路径分隔字元（例如使用 "includes/helper.php" 是错误的写法 — 请使用嵌套物件 "includes": { "helper.php": "..." }）。

步骤参考 (Steps Reference)

每一个步骤都需要包含 "step": "<名称>"。任何步骤皆可选择性加入 "progress": { "weight": 1, "caption": "Installing..." } 以在界面上显示进度反馈。

外挂与主题安装

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

独立启用 (Activation standalone)

仅在外挂/主题已存在于磁碟中时需要（例如透过 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');" }

重要陷阱： 必须载入 require '/wordpress/wp-load.php'; 才能使用任何 WordPress 函式。

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	（无属性）

常见模式 (Common Patterns)

行内 mu-plugin (快速自订程式码)

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins 会自动载入 — 无需启用，也不需要 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": "/"
  }
}

常见错误 (Common Mistakes)

错误写法	正确写法
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';
凭空捏造最上层键名	仅有文档记载的键名能够运作 — Schema 会拒绝未知的属性
为 GitHub 凭空造出代理 URL	请使用 git:directory 资源型态
使用分支/标籤 ref 时漏掉 refType	此项为必填 — 漏掉时仅有 "HEAD" 能正常解析
在 literal:directory 的 files 值中使用资源参考	值必须是纯字串（内容）或物件（子目录） — 绝对不能是资源参考
features.debug 或其他虚构的 feature 键名	features 仅支援 networking 与 intl — 启错模式请使用 constants: { "WP_DEBUG": true }
在 mu-plugin 程式码中使用 require wp-load.php	仅在 runPHP 步骤中需要 — mu-plugins 本身已在 WordPress 环境内执行
使用 .org 网域的 Schema URL	必须为 playground.wordpress.net，而非 playground.wordpress.org

完整参考 (Full Reference)

本 Skill 涵盖了最常用的步骤与模式。如需完整的 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

Bundle 为独立的打包包，内部包含 blueprint.json 以及其所参考的所有资源（外挂、主题、WXR 档案等）。与其将资源托管于外部，不如将其打包