WordPress区块开发指南：创建、修改、迁移与调试Gutenberg区块

wp-block-development by automattic/agent-skills

108 周安装量

195 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/automattic/agent-skills --skill wp-block-development

开发内容管理系统 WordPress

🇨🇳中文介绍

WP 区块开发

何时使用

在以下区块相关工作时使用此技能：

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

所需输入

仓库根目录和目标（插件 vs 主题 vs 完整站点）。
区块名称/命名空间及其位置（如果已知，提供 block.json 的路径）。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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 会导致“无效区块”
添加属性但未正确定义 source/serialization 会导致“属性未保存”

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

优先使用基于元数据的 PHP 注册，特别是在以下情况：

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

references/registration.md

6) 实现 edit/save/render 模式

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

编辑器：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（常见）→ 用于本地 WordPress + E2E

references/tooling-and-testing.md

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

故障模式 / 调试

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

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

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

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

🇺🇸English

WP Block Development

When to use

Use this skill for block work such as:

creating a new block, or updating an existing one
changing block.json (scripts/styles/supports/attributes/render/viewScriptModule)
fixing “block invalid / not saving / attributes not persisting”
adding dynamic rendering (render.php / render_callback)
block deprecations and migrations (deprecated versions)
build tooling for blocks (@wordpress/scripts, @wordpress/create-block, wp-env)

Inputs required

Repo root and target (plugin vs theme vs full site).
The block name/namespace and where it lives (path to block.json if known).
Target WordPress version range (especially if using modules / viewScriptModule).

Procedure

0) Triage and locate blocks

Run triage:
- node skills/wp-project-triage/scripts/detect_wp_project.mjs
List blocks (deterministic scan):
- node skills/wp-block-development/scripts/list_blocks.mjs
Identify the block root (directory containing block.json) you’re changing.

If this repo is a full site (wp-content/ present), be explicit about which plugin/theme contains the block.

1) Create a new block (if needed)

If you are creating a new block, prefer scaffolding rather than hand-rolling structure:

Use @wordpress/create-block to scaffold a modern block/plugin setup.
If you need Interactivity API from day 1, use the interactive template.

Read:

references/creating-new-blocks.md

After scaffolding:

Re-run the block list script and confirm the new block root.
Continue with the remaining steps (model choice, metadata, registration, serialization).

2) Ensure apiVersion 3 (WordPress 6.9+)

WordPress 6.9 enforces apiVersion: 3 in the block.json schema. Blocks with apiVersion 2 or lower trigger console warnings when SCRIPT_DEBUG is enabled.

Why this matters:

WordPress 7.0 will run the post editor in an iframe regardless of block apiVersion.
apiVersion 3 ensures your block works correctly inside the iframed editor (style isolation, viewport units, media queries).

Migration: Changing from version 2 to 3 is usually as simple as updating the apiVersion field in block.json. However:

Test in a local environment with the iframe editor enabled.
Ensure any style handles are included in block.json (styles missing from the iframe won't apply).
Third-party scripts attached to a specific window may have scoping issues.

Read:

references/block-json.md (apiVersion and schema details)

3) Pick the right block model

Static block (markup saved into post content): implement save(); keep attributes serialization stable.
Dynamic block (server-rendered): use render in block.json (or render_callback in PHP) and keep save() minimal or null.
Interactive frontend behavior :
- Prefer viewScriptModule for modern module-based view scripts where supported.
- If you're working primarily on data-wp-* directives or stores, also use wp-interactivity-api.

4) Update `block.json` safely

Make changes in the block’s block.json, then confirm registration matches metadata.

For field-by-field guidance, read:

references/block-json.md

Common pitfalls:

changing name breaks compatibility (treat it as stable API)
changing saved markup without adding deprecated causes “Invalid block”
adding attributes without defining source/serialization correctly causes “attribute not saving”

5) Register the block (server-side preferred)

Prefer PHP registration using metadata, especially when:

you need dynamic rendering
you need translations (wp_set_script_translations)
you need conditional asset loading

Read and apply:

references/registration.md

6) Implement edit/save/render patterns

Follow wrapper attribute best practices:

Editor: useBlockProps()
Static save: useBlockProps.save()
Dynamic render (PHP): get_block_wrapper_attributes()

Read:

references/supports-and-wrappers.md
references/dynamic-rendering.md (if dynamic)

7) Inner blocks (block composition)

If your block is a “container” that nests other blocks, treat Inner Blocks as a first-class feature:

Use useInnerBlocksProps() to integrate inner blocks with wrapper props.
Keep migrations in mind if you change inner markup.

Read:

references/inner-blocks.md

8) Attributes and serialization

Before changing attributes:

confirm where the attribute value lives (comment delimiter vs HTML vs context)
avoid the deprecated meta attribute source

Read:

references/attributes-and-serialization.md

9) Migrations and deprecations (avoid "Invalid block")

If you change saved markup or attributes:

Add a deprecated entry (newest → oldest).
Provide save for old versions and an optional migrate to normalize attributes.

Read:

references/deprecations.md

10) Tooling and verification commands

Prefer whatever the repo already uses:

@wordpress/scripts (common) → run existing npm scripts
wp-env (common) → use for local WP + E2E

Read:

references/tooling-and-testing.md

Verification

Block appears in inserter and inserts successfully.
Saving + reloading does not create “Invalid block”.
Frontend output matches expectations (static: saved markup; dynamic: server output).
Assets load where expected (editor vs frontend).
Run the repo’s lint/build/tests that triage recommends.

Failure modes / debugging

If something fails, start here:

references/debugging.md (common failures + fastest checks)
references/attributes-and-serialization.md (attributes not saving)
references/deprecations.md (invalid block after change)

Escalation

If you’re uncertain about upstream behavior/version support, consult canonical docs first:

WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
Gutenberg repo docs for bleeding-edge behaviors

Weekly Installs

108

Repository

automattic/agent-skills

GitHub Stars

195

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode65

claude-code64

cursor61

codex58

gemini-cli58

github-copilot55

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

WordPress区块开发指南：创建、修改、迁移与调试Gutenberg区块

🇨🇳中文介绍

WP 区块开发

何时使用

所需输入

相关 Skills

操作流程

0) 问题排查与区块定位

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

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

3) 选择合适的区块模型

4) 安全地更新 block.json

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

6) 实现 edit/save/render 模式

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

8) 属性与序列化

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

10) 工具与验证命令

验证

故障模式 / 调试

升级

🇺🇸English

WP Block Development

When to use

Inputs required

Procedure

0) Triage and locate blocks

1) Create a new block (if needed)

2) Ensure apiVersion 3 (WordPress 6.9+)

3) Pick the right block model

4) Update block.json safely

5) Register the block (server-side preferred)

6) Implement edit/save/render patterns

7) Inner blocks (block composition)

8) Attributes and serialization

9) Migrations and deprecations (avoid "Invalid block")

10) Tooling and verification commands

Verification

Failure modes / debugging

Escalation

最新 Skills

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

4) Update `block.json` safely