名称: wp-block-development 描述: “在开发WordPress（古腾堡）区块时使用：block.json元数据、register_block_type(_from_metadata)、属性/序列化、supports、动态渲染（render.php/render_callback）、弃用/迁移、viewScript与viewScriptModule对比，以及@wordpress/scripts/@wordpress/create-block构建和测试工作流。” 兼容性: “目标WordPress 6.9+（PHP 7.2.24+）。基于文件系统的代理，使用bash + node。部分工作流需要WP-CLI。”

WordPress区块开发

何时使用

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

创建新区块或更新现有区块
修改block.json（脚本/样式/supports/属性/渲染/viewScriptModule）
修复“区块无效 / 无法保存 / 属性未持久化”问题
添加动态渲染（render.php / render_callback）
区块弃用和迁移（deprecated版本）
区块构建工具（@wordpress/scripts、@wordpress/create-block、wp-env）

所需输入

仓库根目录和目标（插件 vs 主题 vs 完整站点）。
区块名称/命名空间及其位置（如果已知，提供block.json的路径）。
目标WordPress版本范围（特别是使用模块 / viewScriptModule时）。

操作流程

0) 问题排查与定位区块

运行排查：
- node skills/wp-project-triage/scripts/detect_wp_project.mjs
列出区块（确定性扫描）：
- node skills/wp-block-development/scripts/list_blocks.mjs
识别您要更改的区块根目录（包含block.json的目录）。

如果此仓库是完整站点（存在wp-content/），请明确指出哪个插件/主题包含该区块。

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

如果您要创建新区块，优先使用脚手架而非手动构建结构：

使用@wordpress/create-block来搭建现代区块/插件设置。
如果从一开始就需要交互性API，请使用交互式模板。

阅读：

references/creating-new-blocks.md

搭建完成后：

重新运行区块列表脚本并确认新的区块根目录。
继续后续步骤（模型选择、元数据、注册、序列化）。

2) 确保apiVersion为3（WordPress 6.9+）

WordPress 6.9在block.json模式中强制要求apiVersion: 3。当SCRIPT_DEBUG启用时，apiVersion为2或更低的区块会触发控制台警告。

为何重要：

WordPress 7.0将无论区块apiVersion如何，都在iframe中运行文章编辑器。
apiVersion 3确保您的区块在iframe编辑器内正常工作（样式隔离、视口单位、媒体查询）。

迁移： 从版本2更改为3通常只需更新block.json中的apiVersion字段。但是：

在启用iframe编辑器的本地环境中进行测试。
确保任何样式句柄都包含在block.json中（iframe中缺失的样式将不会应用）。
附加到特定window的第三方脚本可能存在作用域问题。

阅读：

references/block-json.md（apiVersion和模式详情）

3) 选择合适的区块模型

静态区块（标记保存到文章内容中）：实现save()；保持属性序列化稳定。
动态区块（服务器渲染）：在block.json中使用render（或在PHP中使用render_callback），并保持save()最小化或为null。
交互式前端行为：
- 在支持的情况下，优先使用viewScriptModule处理基于模块的现代视图脚本。
- 如果您主要处理data-wp-*指令或存储，也请使用wp-interactivity-api。

4) 安全地更新`block.json`

在区块的block.json中进行更改，然后确认注册与元数据匹配。

有关字段级指导，请阅读：

references/block-json.md

常见陷阱：

更改name会破坏兼容性（将其视为稳定的API）
更改已保存的标记而不添加deprecated会导致“无效区块”
添加属性而未正确定义源/序列化会导致“属性未保存”

5) 注册区块（优先服务器端）

优先使用元数据进行PHP注册，特别是当：

您需要动态渲染
您需要翻译（wp_set_script_translations）
您需要条件性资产加载

阅读并应用：

references/registration.md

6) 实现编辑/保存/渲染模式

遵循包装器属性最佳实践：

编辑器：useBlockProps()
静态保存：useBlockProps.save()
动态渲染（PHP）：get_block_wrapper_attributes()

阅读：

references/supports-and-wrappers.md
references/dynamic-rendering.md（如果是动态的）

7) 内部区块（区块组合）

如果您的区块是嵌套其他区块的“容器”，请将内部区块视为一等公民功能：

使用useInnerBlocksProps()将内部区块与包装器属性集成。
如果更改内部标记，请记住迁移。

阅读：

references/inner-blocks.md

8) 属性和序列化

在更改属性之前：

确认属性值所在位置（注释分隔符 vs HTML vs 上下文）
避免使用已弃用的meta属性源

阅读：

references/attributes-and-serialization.md

9) 迁移和弃用（避免“无效区块”）

如果您更改已保存的标记或属性：

添加一个deprecated条目（从最新到最旧）。
为旧版本提供save，并可选择提供migrate以规范化属性。

阅读：

references/deprecations.md

10) 工具和验证命令

优先使用仓库已有的工具：

@wordpress/scripts（常见）→ 运行现有的npm脚本
wp-env（常见）→ 用于本地WP + E2E

阅读：

references/tooling-and-testing.md

验证

区块出现在插入器中并可成功插入。
保存 + 重新加载不会产生“无效区块”。
前端输出符合预期（静态：已保存的标记；动态：服务器输出）。
资产在预期位置加载（编辑器 vs 前端）。
运行排查建议的仓库的lint/构建/测试。

故障模式 / 调试

如果出现问题，从这里开始：

references/debugging.md（常见故障 + 最快检查）
references/attributes-and-serialization.md（属性未保存）
references/deprecations.md（更改后区块无效）

升级

如果您不确定上游行为/版本支持，请先查阅权威文档：

WordPress开发者资源（区块编辑器手册、主题手册、插件手册）
Gutenberg仓库文档，了解前沿行为