blueprint

Name: blueprint
Author: wordpress

WordPress Playground Blueprints

概述

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

核心原则： Blueprint 是纯 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" }]
}

顶层属性

所有顶层属性均为可选。仅允许使用文档中列出的 key——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 }` — 仅支持这两个 key，不可包含其他项。`networking` 默认值为 `true`
`phpExtensionBundles`	any	已废弃/不再使用；Schema 不对该值作限制，建议从 Blueprint 中移除
`extraLibraries`	array	`["wp-cli"]` — 当存在任意 `wp-cli` 步骤时会自动包含
`constants`	object	`defineWpConfigConsts` 的简写形式。值类型支持：string/boolean/number
`plugins`	array	`installPlugin` 步骤的简写形式。数组元素为字符串，代表 wp.org 的 slug
`siteOptions`	object	`setSiteOptions` 的简写形式
`login`	boolean or 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"。形如 "7.4.1" 的补丁版本号无效。请查阅 Schema 以确认当前支持的版本。
wp: 近期的大版本号、"latest"、"beta"、"nightly"/"trunk"，或指向自定义 zip 的 URL。对于仅使用 PHP 的 Playground 环境，Schema 也接受 false；但请勿将 wp: false 与 WordPress 专属字段（如 plugins、siteOptions、login）或 WordPress 专属步骤混合使用。

简写属性 vs 显式步骤

简写属性（login、plugins、siteOptions、constants）会被展开并以未指定的顺序追加到 steps 最前面。如果对执行顺序有严格要求，请显式使用 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`	引用 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": "/"
}

当 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 采用嵌套对象来表示子目录——key 为文件名或目录名，value 必须是 纯字符串（文件内容）或对象（子目录）。绝对不要在 value 中使用资源引用。
切勿在 key 中使用路径分隔符（例如使用 "includes/helper.php" 是错误的，应使用嵌套的 "includes": { "helper.php": "..." } 对象）。

步骤参考

每个 step 都必须包含 "step": "<name>"。任何 step 都可以包含可选的 "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 必须传入一个 DirectoryReference（literal:directory 或 git:directory）作为 filesTree —— 不能直接传普通对象。

其他文件操作：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 会自动加载 — 无需手动激活，也无需 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` 的 key 中使用路径分隔符	子目录请使用嵌套对象结构
运行 `runPHP` 时未引用 `wp-load.php`	调用 WP 函数时务必引入 `require '/wordpress/wp-load.php';`
自创顶层 key	仅支持文档中记载的 key — Schema 会直接拒绝未知属性
为 GitHub 自创代理 URL	统一使用 `git:directory` 资源类型
`ref` 为分支或标签时漏掉 `refType`	必填项 —— 不填的话只有 `"HEAD"` 能正常工作
在 `literal:directory` 的 `files` 值中使用资源引用	值必须是纯字符串（文件内容）或对象（子目录） —— 绝不能放资源引用
`features.debug` 或其他自创功能 key	`features` 仅支持 `networking` 和 `intl` —— 开启调试模式请用 `constants: { "WP_DEBUG": true }`
在 mu-plugin 代码中包含 `require wp-load.php`	仅在 `runPHP` 步骤中需要 —— mu-plugin 本身就在 WordPress 内部运行
Schema URL 使用了 `.org` 域名	必须是 `playground.wordpress.net`，而不是 `playground.wordpress.org`

完整参考

本 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 文件等）的自包含数据包。无需将资源托管在外部，而是直接打包在内

你可能还喜欢

camsnap

386Ktesting-qa

Capture frames or clips from RTSP/ONVIF cameras.

openclaw

获取

feature-flags

249Ktesting-qa

Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.