如何用 WordPress Agent Skills 开发 Gutenberg 区块：block.json、apiVersion 3 与弃用迁移完整指南-开发者社区

如何用 WordPress Agent Skills 开发 Gutenberg 区块：block.json、apiVersion 3 与弃用迁移完整指南

【免费下载链接】agent-skillsExpert-level WordPress knowledge for AI coding assistants - blocks, themes, plugins, and best practices项目地址: https://gitcode.com/gh_mirrors/agents/agent-skills

WordPress Agent Skills是 GitHub 加速计划下 agent-skills 项目的一部分，它把"专家级 WordPress 知识"打包成 AI 编码助手（Claude、Copilot、Cursor、Codex 等）能直接执行的指令、清单与脚本。对开发者来说，它的价值在于：让 AI 不再生成过时的预 Gutenberg 代码，而是自动遵循block.json规范、apiVersion 3 要求和弃用迁移最佳实践，从源头避免"Invalid block"报错。

🧩 什么是 WordPress Agent Skills

每个"技能（Skill）"都是一个自包含的文件夹：一份主指令、若干深度参考文档，以及一些确定性的辅助脚本。

主指令：告诉 AI什么时候用、按什么步骤做、如何验证
参考文档：针对某个具体主题的深入说明
辅助脚本：负责项目探测、区块扫描等确定性操作

区块开发相关的核心技能位于 wp-block-development，它专门覆盖block.json元数据、属性序列化、动态渲染以及弃用与迁移。

🚀 快速上手：一条命令安装区块技能

最快的安装方式是使用一条命令（无需手动克隆）：

npx skills add WordPress/agent-skills --skill wp-block-development

全局安装：加--global参数，技能会安装到你的主目录，对所有项目生效。
项目安装：默认安装到当前仓库（如.claude/skills/），可提交到版本库与团队共享。
手动安装：直接把skills/下的某个技能文件夹复制到你 AI 助手的指令目录即可。

安装后，当你让 AI 助手处理 WordPress 区块代码时，它就会阅读这些技能并遵循文档中记录的标准流程，而不是"凭空猜测"。

🪪 认识 block.json：区块的"身份证"

block.json是 Gutenberg 区块的元数据文件，相当于区块的"身份证"，声明了它的名字、图标、资产、支持与属性。编辑它时，有几条实践规则非常重要：

把name当作稳定 API——重命名会直接破坏已保存的内容。
优先在不改变已保存 HTML 的前提下新增功能；若必须改 HTML，就添加deprecated版本。
让资产保持作用域：编辑器专属资产不应被打包到前端。

下面是block.json中几个"实战中真正重要"的资产字段：

字段	作用
`editorScript`/`editorStyle`	仅编辑器使用的资产
`script`/`style`	编辑器与前端共用
`viewScript`/`viewStyle`	前端视图资产
`viewScriptModule`	基于模块的前端脚本（较新 WP）
`render`	指向动态区块的 PHP 渲染文件

逐字段的详细讲解见 block-json.md。

⚡ 为什么必须升级到 apiVersion 3

这是本次更新的"重点"。WordPress 6.9+ 要求block.json使用apiVersion: 3：

区块 JSON 模式只校验apiVersion: 3的区块，仍停留在 1 或 2 的区块在开启SCRIPT_DEBUG时会触发控制台警告。
WordPress 7.0 将始终使用 iframe 编辑器（与 apiVersion 无关）。
升到 3 才能保证区块在 iframe 编辑器中正常工作：样式隔离（后台 CSS 不再污染编辑器内容）、正确的视口单位（vw、vh）、原生媒体查询。

从 2 迁移到 3 通常很简单，只需更新block.json里的apiVersion字段，但建议按下面清单核对：

把apiVersion改为3。
确保所有 style 句柄都声明在block.json（未被包含的样式在 iframe 里不会加载）。
测试依赖第三方脚本的区块（window作用域可能不同）。
添加$schema，提升编辑器工具链与校验体验。

💡 若你在编辑器里看到样式在前端生效、编辑器里却不生效，多半就是 style 句柄没写进block.json。

完整迁移说明见 block-json.md 与 debugging.md。

🧱 三种区块模型：静态、动态与交互

选对"区块模型"，能避免后续大量返工：

模型	实现方式	适用场景
静态区块	实现`save()`，标记直接存入文章	内容固定、无需服务器参与
动态区块	`block.json`中用`render`（或 PHP 的`render_callback`），`save()`置空或最简	服务器渲染、数据动态变化
交互区块	优先`viewScriptModule`+`data-wp-*`指令	前端交互行为

动态区块请在 PHP 渲染输出中始终使用get_block_wrapper_attributes()，以保留 supports 生成的类与样式，详见 dynamic-rendering.md。
若需要前端交互，配合 wp-interactivity-api 技能使用。

创建新区块时，优先使用@wordpress/create-block脚手架（可选 TypeScript、静态/动态、是否交互）；若第一天就要 Interactivity API，可直接用官方交互模板。参见 creating-new-blocks.md。

♻️ 弃用与迁移：告别 "Invalid block" 报错

当你修改了已保存的 HTML 或属性结构却没有提供迁移路径，用户打开旧文章就会看到"This block contains unexpected or invalid content"。正确做法是：

在 JS 区块注册中向deprecated数组添加旧实现，按"新 → 旧"排序。
每个deprecated条目可包含attributes、supports、save、migrate。
用save描述旧版本的输出，必要时用migrate把旧属性归一化为新结构。

两条实用护栏：保留 fixture（为每个废弃版本存一份示例内容）；拿不准时就添加迁移路径，而不是悄悄改动选择器。详见 deprecations.md。

⚠️ 关于属性序列化：属性值可能来自注释分隔符 JSON、已保存 HTML 或上下文；避免使用已废弃的meta属性来源，它会带来长期隐患。完整说明见 attributes-and-serialization.md。

🤖 让 AI 帮你走完整套流程

安装技能后，AI 助手会按标准流程操作，而不是一步到位地"猜"。核心步骤包括：

项目分诊：运行 detect_wp_project.mjs 自动探测项目类型、工具链与版本。
列出区块：运行 list_blocks.mjs 做确定性扫描，定位要改的区块根目录。
安全更新block.json并确认注册与元数据一致（优先使用register_block_type_from_metadata()，见 registration.md）。
按需添加deprecated与迁移，最后验证"旧内容不再报 Invalid block"。

这套流程的完整验证标准与一个真实场景（"安全地给区块新增属性"）可参考 block-add-attribute-and-migrate.json，构建与测试工具链说明见 tooling-and-testing.md。

🛠️ 常见问题速查

遇到下面这些典型故障，可快速对号入座：

区块不出现在插入器：确认block.json的name有效且已注册、构建产物存在、脚本已加载、PHP 注册在init钩子上运行。
"Invalid block" 报错：你改了已保存 HTML 或属性解析——添加deprecated版本和迁移路径，并用一篇含旧标记的旧文章复现。
属性保存不上：确认属性定义与实际标记一致、避免脆弱选择器、弃用meta来源。
apiVersion 控制台警告（6.9+）：把apiVersion升到3（仅SCRIPT_DEBUG为 true 时出现）。
iframe 编辑器里样式不生效：确保 style 句柄都写进了block.json。

逐条排查方法见 debugging.md。

📌 小结

用WordPress Agent Skills开发 Gutenberg 区块的关键，是把三件事做扎实：用block.json声明好区块身份、升级到 apiVersion 3 以适配 iframe 编辑器、在改动标记或属性时用deprecated与migrate做迁移。装上 wp-block-development 技能后，AI 助手会替你走完全流程——从项目分诊、区块扫描，到注册、渲染与迁移验证，让"专家级 WordPress 知识"真正成为你日常开发的一部分。