名称: wp-block-themes 描述: “在开发WordPress区块主题时使用：theme.json（全局设置/样式）、模板和模板部件、模式、样式变体，以及站点编辑器故障排除（样式层次结构、覆盖、缓存）。” 兼容性: “目标WordPress 6.9+（PHP 7.2.24+）。基于文件系统的代理，使用bash + node。某些工作流需要WP-CLI。”

WP区块主题

何时使用

此技能用于区块主题相关工作，例如：

编辑 theme.json（预设、设置、样式、按块样式）
添加或更改模板（templates/*.html）和模板部件（parts/*.html）
添加模式（patterns/*.php）并控制插入器中显示的内容
添加样式变体（styles/*.json）
调试“样式未应用”/“编辑器未反映theme.json”问题

所需输入

仓库根目录以及目标主题（如果存在多个主题，则为主题目录）。
目标WordPress版本范围（theme.json版本和功能因核心版本而异）。
问题出现的位置：站点编辑器、文章编辑器、前端，或全部。

操作流程

0) 问题排查与定位区块主题根目录

运行排查：
- node skills/wp-project-triage/scripts/detect_wp_project.mjs
检测主题根目录 + 关键文件夹：
- node skills/wp-block-themes/scripts/detect_block_themes.mjs

如果存在多个主题，选择一个并将所有更改限定在该主题根目录下。

1) 创建新的区块主题（如果需要）

如果您要从头开始创建新的区块主题（或转换经典主题）：

建议从已知良好的脚手架开始（或从WP环境导出），而不是猜测文件布局。
明确说明最低支持的WordPress版本，因为 theme.json 架构版本不同。

阅读：

references/creating-new-block-theme.md

创建主题根目录后，重新运行 detect_block_themes 并继续以下步骤。

2) 确认主题类型和覆盖预期

区块主题指标：
- 存在 theme.json
- 存在 templates/ 和/或 parts/
记住样式层次结构：
- 核心默认值 → theme.json → 子主题 → 用户自定义
- 用户自定义可能会使theme.json的编辑看起来“被忽略”

阅读：

references/debugging.md（样式层次结构 + 最快检查）

3) 安全地进行 `theme.json` 更改

决定您要更改的是：

设置（UI允许的内容）：预设、排版比例、颜色、布局、间距
样式（默认外观）：针对元素/块的类CSS规则

阅读：

references/theme-json.md

4) 模板和模板部件

模板位于 templates/ 下，格式为HTML。
模板部件位于 parts/ 下，不得嵌套在子目录中。

阅读：

references/templates-and-parts.md

5) 模式

当您需要主题拥有的模式时，建议使用 patterns/ 下的文件系统模式。

阅读：

references/patterns.md

6) 样式变体

样式变体是位于 styles/ 下的JSON文件。注意：一旦用户选择了样式变体，该选择会存储在数据库中，因此更改文件可能不会自动“更新用户看到的内容”。

阅读：

references/style-variations.md

验证

站点编辑器在预期位置反映更改（样式UI、模板、模式）。
前端以预期样式渲染。
如果样式未更改，请确认用户自定义是否覆盖了主题默认值。
如果涉及资源（字体、自定义JS/CSS构建），请运行仓库的构建/检查脚本。

故障模式 / 调试

从以下开始：

references/debugging.md

常见问题：

错误的主题根目录（编辑了非活动主题）
用户自定义覆盖了您的默认设置
无效的 theme.json 结构/拼写错误导致无法应用
模板/部件位于错误的文件夹中（或部件嵌套）

升级处理

如果上游行为不明确，请查阅权威文档：

主题手册和区块编辑器手册，了解 theme.json、模板、模式和样式变体。