前言¶
改 block.json、換保存結構、加動態渲染，很容易在編輯器裏看到「Invalid block」、屬性存不住，或在 WordPress 7.0 的 iframe 編輯器裏樣式對不上。區塊開發牽涉元數據、序列化、資源作用域和 deprecation 鏈，步驟順序錯了，問題往往要回頭拆。
下面介紹 WordPress 官方 Agent Skills 裏的 wp-block-development：按固定流程做新建、註冊、渲染和遷移，並指向倉庫內 reference 文檔與腳本。
這是什麼¶
wp-block-development 是 WordPress agent-skills 倉庫中的 Skill，面向 Gutenberg 區塊從腳手架到上線的完整工作流。
官方描述覆蓋：block.json 元數據、register_block_type / register_block_type_from_metadata、attributes 與序列化、supports、動態渲染（render.php / render_callback）、deprecations 遷移、viewScript 與 viewScriptModule，以及 @wordpress/scripts、@wordpress/create-block 的構建與測試。
兼容性（SKILL 元數據）： 目標 WordPress 7.0+（PHP 7.4.0+）；基於文件系統的 Agent，需要 bash 與 node；部分流程依賴 WP-CLI。
核心功能¶
資料中列出的能力如下，均對應 SKILL 中的 Procedure 與 references。
| 方向 | 內容 |
|---|---|
| 項目定位 | 配合 wp-project-triage 的 detect_wp_project.mjs，用 list_blocks.mjs 掃描含 block.json 的區塊根目錄 |
| 新建區塊 | 推薦 @wordpress/create-block 腳手架；需要 Interactivity API 時用 interactive 模板 |
| apiVersion 3 | WordPress 6.9+ 在 schema 上強制 apiVersion 3；爲 iframe 編輯器（WordPress 7.0）準備樣式與腳本作用域 |
| 區塊模型 | 靜態（save() + 穩定序列化）、動態（render / render_callback）、前端交互（優先 viewScriptModule，Interactivity 用 wp-interactivity-api） |
| 元數據與安全修改 | block.json 字段說明見 references/block-json.md；改 name 會破壞兼容；改保存結構需 deprecated |
| 服務端註冊 | PHP 元數據註冊，便於翻譯、條件加載與動態渲染（references/registration.md） |
| 編輯 / 保存 / 渲染 | useBlockProps、useBlockProps.save()、get_block_wrapper_attributes()；內嵌塊用 useInnerBlocksProps() |
| 屬性與序列化 | 確認 comment / HTML / context 來源；避免已廢棄的 meta source（references/attributes-and-serialization.md） |
| 遷移 | deprecated 從新到舊、save 與可選 migrate（references/deprecations.md） |
| 工具鏈 | 沿用倉庫已有的 @wordpress/scripts、wp-env 等（references/tooling-and-testing.md） |
驗證清單： 插入器可插入；保存重載無 Invalid block；前端輸出符合靜態或動態預期；編輯器與前端資源加載正確；跑 triage 推薦的 lint / build / test。
排錯入口： references/debugging.md，以及屬性、deprecation 相關 reference。
安裝與啓用¶
通過 officialskills.sh 公佈的命令安裝到本地 Skills 環境：
npx skills add https://github.com/WordPress/agent-skills --skill wp-block-development
也可把 Skill 目錄鏈接交給支持 Agent Skills 的編碼助手，由其按項目約定安裝：
https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-block-development
安裝後，Agent 按 SKILL.md 的 Procedure 執行；倉庫內 references/ 與 scripts/ 爲配套說明與腳本，無需單獨「配置文件」字段（資料未給出 Cursor / Codex CLI / Claude Code 的差異說明，此處不展開）。
典型用法¶
使用前準備：倉庫根路徑、目標載體（插件 / 主題 / 整站）、區塊命名空間與 block.json 路徑、目標 WordPress 版本區間（尤其涉及 module / viewScriptModule）。整站倉庫需明確區塊落在哪個插件或主題。
0）定位區塊¶
先做項目分診，再列出區塊目錄：
node skills/wp-project-triage/scripts/detect_wp_project.mjs
node skills/wp-block-development/scripts/list_blocks.mjs
確認要改的目錄即爲包含 block.json 的區塊根。
1）新建區塊（可選）¶
用 @wordpress/create-block 腳手架，閱讀 references/creating-new-blocks.md。腳手架完成後再次運行 list_blocks.mjs 確認路徑，再繼續元數據與註冊。
2）升級到 apiVersion 3¶
在 block.json 中設置 apiVersion: 3（自 v2 遷移通常只改該字段，但需在啓用 iframe 編輯器的本地環境驗證）。確保樣式句柄寫在 block.json 中，避免 iframe 內樣式缺失；注意第三方腳本對 window 的作用域。細節見 references/block-json.md。
3）改元數據並註冊¶
按靜態 / 動態 / 交互模型實現 edit / save / render，服務端優先 register_block_type_from_metadata。動態塊見 references/dynamic-rendering.md；容器塊見 references/inner-blocks.md。
4）改保存結構時加 deprecation¶
若調整已發佈內容中的 markup 或屬性：
- 在
deprecated中從新版本到舊版本依次聲明； - 爲舊版提供
save，必要時用migrate規範化 attributes。
詳見 references/deprecations.md，可避免保存後出現 Invalid block。
5）構建與本地驗證¶
使用項目已有的 npm script（@wordpress/scripts）或 wp-env 做本地 WordPress 與 E2E，參見 references/tooling-and-testing.md。
適用場景與注意¶
適合：
- 新建或維護插件 / 主題中的 Gutenberg 區塊；
- 修復 block invalid、不保存、屬性不持久化；
- 爲靜態塊增加
render.php或服務端render_callback； - 規劃 apiVersion 2 → 3，適配 WordPress 7.0 編輯器 iframe；
- 容器塊與 Inner Blocks 的包裝屬性與遷移。
限制與注意：
- 目標環境爲 WordPress 7.0+；舊版本行爲以官方 Developer Resources 與 Gutenberg 文檔爲準（SKILL 中的 Escalation 節）。
- 部分步驟依賴 WP-CLI 與 node 腳本，純手動改文件而不跑 list / triage 時，Agent 仍可按 reference 指引，但定位成本更高。
name視爲穩定 API；未配 deprecation 就改保存 HTML，是資料中明確列出的常見坑。
結尾¶
wp-block-development 把區塊開發拆成可覈對的分步流程：先掃 block.json、選對靜態或動態模型、安全改元數據、用 deprecation 兜住歷史內容，並用倉庫內 reference 對齊註冊與序列化。它是 WordPress 在 Agent Skills 生態裏針對核心編輯體驗的一條官方路徑。
