Blueprint 用于声明式配置 WordPress Playground 实例。它的核心载体是一个 JSON 文件，用来安装插件和主题、设置站点选项、运行 PHP/SQL、操作文件以及导入内容等。核心原则是：Blueprint 是仅由受信任 JSON 组成的声明，不包含任意 JavaScript，可在 Web、Node.js 和 CLI 上运行。
顶层属性（全部可选，仅允许已记录的键，未知属性会被模式拒绝）：$schema（固定为 https://playground.wordpress.net/blueprint-schema.json）、landingPage（相对路径，如 /wp-admin/）、description（已弃用的顶层描述，新 Blueprint 建议改用 meta.description）、meta（{ title, author, description?, categories? }，title 与 author 必填）、preferredVersions（{ php, wp }，存在时两者都必填）、features（仅支持 networking? 与 intl? 两个键，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，模式也接受 false 表示仅 PHP 的 Playground，但此时不要与 plugins、siteOptions、login 等仅 WordPress 的字段或步骤混用。
简写与步骤：简写（login、plugins、siteOptions、constants）会以未指定顺序展开并前置到 steps；当执行顺序重要时应使用显式步骤。
资源引用用于告诉 Playground 在哪里找到文件，被 installPlugin、installTheme、writeFile、writeFiles、importWxr 等使用。类型包括：wordpress.org/plugins（slug）、wordpress.org/themes（slug）、url（url）、git:directory（url、ref）、literal（name、contents）、literal:directory（name、files）、bundled（path，引用捆绑包内文件）、zip（inner，把其他资源包成 ZIP）。使用分支或标签名作为 ref 时必须设置 refType（"branch" | "tag" | "commit" | "refname"），否则只有 "HEAD" 能可靠解析；path 可选择子目录，默认仓库根目录。literal:directory 的 files 用嵌套对象表示子目录，键为文件名或目录名，值为纯字符串（文件内容）或对象（子目录），绝不能用资源引用作为值，也不要在键中使用路径分隔符。
步骤参考：每个步骤都需要 "step": "<name>"，任何步骤都可选带 "progress": { "weight": 1, "caption": "..." }。安装类步骤使用 pluginData/themeData，而非已弃用的 pluginZipFile/themeZipFile；pluginData/themeData 接受任意 FileReference 或 DirectoryReference，如 zip URL、wordpress.org/plugins slug、git:directory 或 literal:directory。options.activate 控制激活，使用 installPlugin/installTheme 时无需单独再写 activatePlugin/activateTheme；ifAlreadyInstalled 取值 "overwrite" | "skip" | "error"。独立激活步骤 activatePlugin（pluginPath）与 activateTheme（themeFolderName）仅在插件/主题已在磁盘上（如 writeFile/writeFiles 之后）时才需要。
文件操作：writeFile（path、data，data 可为纯字符串或资源引用）、writeFiles（writeToPath、filesTree，filesTree 必须是 DirectoryReference，即 literal:directory 或 git:directory，不能是普通对象）；其他文件操作包括 mkdir、cp、mv、rm、rmdir、unzip。
运行代码：runPHP（code，使用任何 WordPress 函数前必须 require '/wordpress/wp-load.php';）、wp-cli（command，步骤名带连字符，不是 cli 或 wpcli）、runSql（sql 资源引用）。
站点配置：setSiteOptions、defineWpConfigConsts、setSiteLanguage、defineSiteUrl。其他步骤包括 login、enableMultisite、importWxr、importThemeStarterContent、importWordPressFiles、request、updateUserMeta、runWpInstallationWizard、resetData。
常见模式示例包括：内联 mu-plugin（mu-plugins 自动加载，无需激活，也无需 require wp-load.php）、内联多文件插件（用 literal:directory 写入后单独 activatePlugin 激活）、从 GitHub 分支安装插件（git:directory，带 ref 与 refType）。资料同时列出常见错误与正确做法，例如 pluginZipFile/themeZipFile 应改为 pluginData/themeData；"step": "cli" 应改为 "step": "wp-cli"；writeFiles.filesTree 必须用 literal:directory 或 git:directory；literal:directory 的 files 值不得用资源引用；features 只支持 networking 与 intl，调试模式应改用 constants: { "WP_DEBUG": true }；模式 URL 必须是 playground.wordpress.net，而不是 .org 等。
Blueprint 捆绑包是自包含包，包含 blueprint.json 及其引用的所有资源（插件、主题、WXR 文件等），插件与主题需先压缩再打包，引用时使用 { "resource": "bundled", "path": "/my-plugin.zip" }。分发格式包括：远程 ZIP（网站 https://playground.wordpress.net/?blueprint-url=https://example.com/bundle.zip）、本地 ZIP（CLI npx @wp-playground/cli server --blueprint=./bundle.zip）、本地目录（CLI 需加 --blueprint-may-read-adjacent-files）、Git 仓库目录（blueprint-url 指向包含 blueprint.json 的仓库目录）。注意：本地目录捆绑包必须使用 --blueprint-may-read-adjacent-files，否则任何 bundled 引用都会报 File not found；ZIP 捆绑包不需要该标志。测试方式：内联 Blueprint（压缩 JSON、encodeURIComponent 编码一次后拼到 https://playground.wordpress.net/# 打开，过大的 Blueprint 可能超出浏览器 URL 长度限制，应改用 CLI 或托管 URL）、本地 CLI 交互式服务器、无头验证（npx @wp-playground/cli run-blueprint）。完整的 API 与更多步骤（如 runPHPWithOptions、vfs 与 bundled 资源类型）见 Blueprint 文档 https://wordpress.github.io/wordpress-playground/blueprints 与 JSON 模式 https://playground.wordpress.net/blueprint-schema.json。