用途
该技能用于创建、编辑或审查 WordPress Playground 的 Blueprint JSON 文件,触发条件包括提到 blueprints、playground 配置等相关请求。Blueprint 是一个 JSON 文件,以声明式方式配置 WordPress Playground 实例,可安装插件与主题、设置选项、运行 PHP/SQL、操作文件等。核心原则是 Blueprint 为仅含 JSON 的受信任声明,不含任意 JavaScript,可在 Web、Node.js 和 CLI 中工作。
主要能力
- 通过顶层属性配置:$schema、landingPage、meta、preferredVersions、features、extraLibraries、constants、plugins、siteOptions、login、steps。所有属性均为可选,且仅允许文档中列出的键,schema 会拒绝未知属性。
- features 仅支持 networking 与 intl 两个键,networking 默认为 true。
- preferredVersions 中 php 仅支持主次版本(如 "8.3"、"7.4")或 "latest",不支持补丁版本;wp 支持近期主版本、"latest"、"nightly"、"beta" 或自定义 zip 的 URL。
- 提供简写(login、plugins、siteOptions、constants),会被展开并前置到 steps,顺序未指定;需要明确执行顺序时使用显式步骤。
- 资源引用类型:wordpress.org/plugins、wordpress.org/themes、url、git:directory、literal、literal:directory、bundled、zip。
- 步骤参考涵盖:插件与主题安装(installPlugin/installTheme,使用 pluginData/themeData,options.activate 控制激活)、独立激活(activatePlugin/activateTheme)、文件操作(writeFile、writeFiles、mkdir、cp、mv、rm、rmdir、unzip)、运行代码(runPHP、wp-cli、runSql)、站点配置(setSiteOptions、defineWpConfigConsts、setSiteLanguage、defineSiteUrl),以及其他步骤(login、enableMultisite、importWxr、importThemeStarterContent、importWordPressFiles、request、updateUserMeta、runWpInstallationWizard、resetData)。
使用方式
快速入门模板:
{
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
"landingPage": "/wp-admin/",
"preferredVersions": { "php": "8.3", "wp": "latest" },
"steps": [{ "step": "login" }]
}
- 每个步骤需要 "step": "<name>",可选 "progress": { "weight": 1, "caption": "..." } 用于界面反馈。
- 运行代码时:runPHP 中必须 require '/wordpress/wp-load.php'; 才能使用 WordPress 函数;wp-cli 步骤名带连字符,不是 cli 或 wpcli。
- git:directory 引用分支或标签作为 ref 时必须设置 refType("branch" | "tag" | "commit" | "refname"),否则只有 "HEAD" 可靠解析。
- literal:directory 的 files 使用嵌套对象表示子目录,键不得包含路径分隔符,值只能是纯字符串(文件内容)或对象(子目录),不得使用资源引用。
- 测试方式:内联 Blueprint 可将其压缩后前置 https://playground.wordpress.net/# 在浏览器打开;本地 CLI 可使用 npx @wp-playground/cli server --blueprint=./bundle.zip 或目录形式(需 --blueprint-may-read-adjacent-files);无头验证使用 npx @wp-playground/cli run-blueprint。
- 分发格式包括远程 ZIP、本地 ZIP、本地目录、Git 仓库目录。本地目录 bundle 必须传 --blueprint-may-read-adjacent-files,ZIP bundle 不需要。
适用场景
适用于编写或审查 WordPress Playground Blueprint 配置、搭建可复现的 WordPress 演示或测试环境、在 Blueprint 中安装插件主题或导入内容、以及打包与分发 Blueprint Bundles 等场景。
限制
- 仅能用文档中记录的键,schema 会拒绝未知属性。
- features 仅支持 networking 与 intl,不支持 features.debug,调试模式需使用 constants: { "WP_DEBUG": true }。
- literal:directory 的值不能是资源引用。
- 简写展开顺序未指定,执行顺序重要时须用显式步骤。
- schema URL 必须使用 playground.wordpress.net,而非 .org。
- 大型 Blueprint 可能超出浏览器 URL 长度限制,需改用 CLI。