外掛裝了三個，湊出來的提示框還是不對，顏色跟主題的全站樣式對不起來，後台又多出一排用不到的選項，想關掉還得翻遍設定文件找開關在哪裡。多數人卡在這一步，不是不會用 WordPress，而是找不到一個剛好長成心裡那個樣子的區塊。
真正的解法不是再多裝一個外掛，是自己動手寫一個。自訂區塊，是開發者用 PHP 搭配 JavaScript，向 WordPress 註冊出來的一個全新區塊類型，它有自己的名稱、自己的資料欄位、自己在編輯器裡的長相，前台輸出也完全照你寫的邏輯走。跟裝來的區塊比，少了一堆用不到功能的負擔，也不必再拿 CSS 去硬蓋外掛給的樣式。
這條路一開始聽起來像要懂一整套前端框架才敢碰，但其實官方鷹架工具已經把大半的骨架搭好了，你要做的多半是照著填空、弄懂每個檔案在負責什麼。先從自訂區塊跟另一個常被搞混的東西，也就是可重複使用區塊，兩者的差別講起，再一路做出一個真正能用的範例。
自訂區塊是什麼？跟可重複使用區塊的差別
很多人把自訂區塊跟可重複使用區塊當成同一件事，原因是兩者在編輯器裡看起來都在「重複用同一套東西」，但技術上完全是兩條不同的路。自訂區塊指的是寫程式碼向 WordPress 註冊一個新的區塊類型，它有自己的 name、attributes、編輯畫面與輸出邏輯，是一個系統原本不認得、由你新建出來的東西。
可重複使用區塊則早在 WordPress 6.3（2023 年 8 月）就正式更名為「同步樣式」（Synced Patterns）。它的本質，是把既有的區塊組合起來存成一份樣板，插到不同頁面時內容彼此同步，改一處、所有插入的地方跟著更新。這個過程完全不涉及寫程式碼，也不會產生任何新的區塊類型，只是把一堆已經存在的區塊打包重複使用。WordPress 官方文件也把這次更名解釋為讓「同步樣式」併進更廣的「樣式」（Patterns）系統，使用者不用再分辨這是可重複使用區塊還是一般樣式。
至於裝外掛得到的區塊，其實跟自己開發用的是同一套機制，只是換人做而已。別人已經寫好 PHP 跟 JavaScript，把區塊註冊進他的外掛，你裝上去、啟用，系統就認得這個新的區塊類型，原理跟接下來要教的一模一樣。差別只在於，別人開發出來的功能不一定剛好貼你的需求，而自己動手就能照著自己的資料結構跟畫面去設計。
block.json 的官方參考文件把「name」定義成區塊的唯一識別字串，格式必須是命名空間加區塊名稱，例如稍後這篇會實際做出來的pongo-example/highlight-box。這正是自訂區塊在技術上的本體：一個被賦予專屬命名空間、註冊進 WordPress 的全新區塊類型，跟套用現成的樣式或裝一個已經寫好的外掛是完全不同的兩件事。
值得自己開發一個區塊的三種常見情境
承接上一節的定義，接下來的問題是什麼時候該考慮自己開發，而不是繼續找外掛湊合。答案不該只是空泛的「因為更客製化」，實際會觸發這個念頭的通常是三種具體情境。
第一種情境，是內容結構重複出現、但外掛裡剛好沒有對應的款式。比如你的網站每篇文章都需要一個固定樣式的提示框，或是聯絡資訊卡，每次都用段落搭配自訂樣式手動拼湊，拼十次就有十種細微差異。這種「同一種結構會一直重複用到」的訊號，是最常見的開發理由。
第二種情境，是希望區塊的顏色、字級跟著網站全站樣式設定（theme.json）走，而不是外掛自帶一套獨立的樣式系統。WordPress 官方文件指出，block.json 的supports屬性能讓區塊「繼承」核心區塊既有的顏色、排版等設定面板，目的正是確保區塊行為跟核心區塊一致，不必從零重建類似的功能。裝來的外掛區塊常常有自己一套配色邏輯，跟網站的全站樣式對不上，自己開發就能直接接上 theme.json，不用再另外疊 CSS 去校正。
第三種情境，是只需要一兩個簡單功能，卻要為此安裝一整個區塊庫外掛。有些區塊外掛一裝就是幾十種區塊，你真正會用到的可能只有其中一種，其餘的都在後台佔位置、增加載入負擔，也拉長了未來維護跟排除相容性問題的時間。與其為了一個小功能背上整包外掛的維護成本，不如直接寫出剛好符合需求的那一個區塊。
開始寫區塊前，先備好 Node.js 與本機開發環境
進入實作前，有幾樣東西得先備好，免得卡在環境設定上、耽誤了真正該花時間理解的邏輯。首先要有 Node.js 與 npm，這兩者是用來跑官方鷹架工具、以及後續打包程式碼所必須的執行環境。官方@wordpress/create-block套件的文件明確列出版本門檻：Node 版本要在 20.10.0 以上，npm 版本要在 10.2.3 以上。裝之前先確認自己的版本符合，不然鷹架工具會直接跑不起來。
其次，需要一個可以安裝外掛、啟用外掛的 WordPress 環境，不管是本機還是測試站都行。WordPress 官方也提供了wp-env這個以 Docker 為基礎的本機開發工具，它可以在鷹架出來的外掛資料夾裡，直接建立一個乾淨的本機 WordPress 環境。這不是必要條件，若你手邊已經有測試站可以裝外掛，一樣能跟著這篇往下做；但如果沒有，wp-env會省下你另外架站的麻煩，前提是本機要先裝好 Docker。
值得說清楚的是，不需要事先手動裝 webpack、Babel 或 ESLint 這些前端工具鏈的零件。鷹架工具會內建打包設定，這也是官方鷹架工具存在的意義，它把一整套現代前端開發需要的設定都包好了，你不用先去弄懂一整套建置系統才能開始寫區塊。
用 @wordpress/create-block 建出區塊的初始骨架
環境備好之後，第一步就是動手鷹架出一個範例區塊。這篇接下來會用「提示框」當範例，一個能編輯文字、能切換背景色的內容元件，常見於部落格文章裡用來強調重點，後面每一節都圍著它展開。在外掛資料夾（或任意工作目錄）下，執行以下指令：
npx @wordpress/create-block@latest highlight-box --namespace=pongo-exampleCode language: Bash (bash)highlight-box是這次要建的 slug，它同時決定三件事：鷹架出來的資料夾名稱、外掛的名稱，還有區塊在系統內部識別名稱的一部分。指定 slug 會讓工具直接進入「快速模式」，跳過一連串互動式提問，對已經確定範例名稱的情況特別方便。
--namespace則是命名空間，官方文件特別提醒一定要換成自己的，不要沿用預設值create-block。命名空間的作用，是避免不同外掛註冊出來的區塊名稱互相撞在一起，如果多個外掛都用預設命名空間，同名區塊在同一個網站上就會互相蓋掉。這裡把它設成pongo-example，最後區塊的完整識別名稱就會是pongo-example/highlight-box。
如果想要動態渲染的版本（什麼是動態渲染，留到後面「save 與 render.php」那節細講），可以加上--variant=dynamic，官方教學文件裡也是這樣示範的，例如npx @wordpress/create-block@latest copyright-date-block --variant=dynamic。指令跑完之後，到 WordPress 的外掛頁面把它啟用，區塊就能在編輯器的插入器（Inserter）裡搜尋到。
骨架資料夾裡，block.json、edit.js 與 save.js 各自的分工
鷹架跑完會生出一批檔案，第一次打開常常讓人不知道從哪看起。搞懂每個檔案在整個機制裡負責什麼，後面要動手改的內容才有脈絡可循，而不是照抄程式碼卻不知道為什麼。
src/block.json是這個區塊的身分證與設定總表，同一份定義同時提供給伺服器端的 PHP，以及客戶端的 JavaScript 讀取。WordPress 官方文件用一句話總結了這個機制的用意，也就是 block.json 讓同一份 JSON 格式的定義，能同時在伺服器端與客戶端（區塊編輯器）完成註冊，不必再各寫一套定義。
src/index.js是客戶端註冊區塊的進入點，它把 block.json 裡的定義，跟edit.js(以及save.js，若有)串在一起。src/edit.js決定區塊在編輯器畫面裡長什麼樣子、怎麼互動，這是使用者實際打字、調整設定的地方。src/save.js則決定區塊採用「靜態渲染」時，要存進資料庫的 HTML 長什麼樣子；如果選的是動態渲染，可能根本沒有這個檔案，改由render.php負責。
render.php只有動態區塊才會有，它決定的是前台實際輸出的內容。至於打包過後的build/資料夾，才是 WordPress 真正讀取、拿去註冊的版本，src/裡放的只是原始碼，兩者不能混為一談。官方教學文件也點出一個容易被忽略的細節，render.php是專屬於動態渲染的檔案，save.js則是等到教學走到「加入靜態渲染」那一步才會需要新增的東西，兩者不一定同時存在於同一個區塊裡。
block.json 要交代清楚的七個核心欄位
block.json 最常用、幾乎每個區塊都會填的欄位共有七個：name、title、category、icon、description、attributes 與 supports。attributes 跟 supports 份量比較重，這裡先用提示框範例把前五個欄位實際填一遍，建立整體輪廓：
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "pongo-example/highlight-box",
"title": "提示框",
"category": "text",
"icon": "megaphone",
"description": "顯示一段用來強調重點的文字方塊，背景色可從設定面板切換。",
"textdomain": "highlight-box"
}Code language: JSON / JSON with Comments (json)name格式必須是「命名空間/區塊名稱」，只能用小寫英數字、破折號，最多一個斜線，前面提過的pongo-example/highlight-box就是照這個規則來的。title是顯示在插入器裡的名稱，會被翻譯系統處理，所以填中文完全沒問題。
category決定區塊被分到插入器的哪一個分類，核心提供的分類包括 text、media、design、widgets、theme、embed 幾種。這篇的提示框本質上是文字內容，所以歸在text。icon是插入器裡的圖示，可以用官方內建的 Dashicon 名稱代稱(如上面的megaphone)，也可以之後在index.js裡換成完全自訂的 SVG 圖案。description則是滑鼠移到區塊上會顯示的說明文字，幫使用者在還沒點下去之前就知道這個區塊是做什麼用的。
WordPress 官方的 block.json 基礎文件，把 name、title、category、icon、description 這幾個欄位歸類為「區塊的基本識別資訊」，先把這五項填好，這個區塊在插入器裡就已經是個看得懂、找得到的東西，接下來才輪到 attributes 與 supports 去處理實際的資料與樣式行為。
attributes 決定區塊資料儲存在資料庫的方式
區塊最核心的資料機制，是使用者在編輯器裡打了什麼字、選了什麼顏色，系統要怎麼把這些改動記住並存進資料庫。attribute 要在 block.json 裡宣告，至少得指定type，可以是 string、boolean、number、object、array 這幾種。
沿用提示框的例子，先宣告一個叫message的字串型 attribute，用來存放這個提示框裡的文字內容：
"attributes": {
"message": {
"type": "string",
"default": "在這裡輸入重點內容"
}
}Code language: JSON / JSON with Comments (json)宣告好的 attributes 會自動傳進Edit元件與save函式，讓編輯畫面跟前台輸出讀到同一份資料，不需要再另外寫程式碰資料庫。WordPress 官方文件說明了 attributes 的角色，block.json 裡的 attributes 屬性描述的是這個區塊需要的自訂資料、以及這些資料怎麼被儲存，讓編輯器能正確解析這些值，並把它們傳給區塊的 Edit 元件跟 save 函式。
實際存進資料庫時，attributes 會被序列化寫進區塊的 HTML 註解分隔符裡，格式類似<!-- wp:pongo-example/highlight-box {"message":"重點在這裡"} -->。這一段 HTML 註解，就是 WordPress 用來判斷「這是哪一種區塊、資料長什麼樣」的依據，前台跟編輯器都是靠解析這段註解來還原區塊的內容跟狀態。
也不是所有資料都要走自訂 attribute。顏色、字級這類常見設定，交給下一節要提的supports處理，通常更省工，也更符合 WordPress 一貫的操作習慣，讓使用者在你的區塊跟核心區塊之間感受到一致的操作方式。
Edit 元件組成編輯器畫面，useBlockProps 是起點
動手寫edit.js，把提示框範例做出來，一段可編輯文字，加上右側設定面板裡的一個開關。程式碼大致長這樣：
import { useBlockProps, RichText, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
export default function Edit( { attributes, setAttributes } ) {
const { message, isBold } = attributes;
const blockProps = useBlockProps( {
className: isBold ? 'is-style-bold' : undefined,
} );
return (
<>
<InspectorControls>
<PanelBody title={ __( '提示框設定', 'highlight-box' ) }>
<ToggleControl
label={ __( '文字加粗', 'highlight-box' ) }
checked={ isBold }
onChange={ ( value ) => setAttributes( { isBold: value } ) }
/>
</PanelBody>
</InspectorControls>
<div { ...blockProps }>
<RichText
tagName="p"
value={ message }
onChange={ ( value ) => setAttributes( { message: value } ) }
placeholder={ __( '在這裡輸入重點內容…', 'highlight-box' ) }
/>
</div>
</>
);
}Code language: JavaScript (javascript)上面多用了一個布林值 attributeisBold，同樣要記得回到 block.json 把它宣告成"type": "boolean"，原理跟上一節的message一致。useBlockProps()負責把區塊在編輯器裡需要的 CSS 類別與樣式，包括 supports 產生出來的樣式，一併輸出到包裹元素上，少了這個函式，區塊會少掉一整批內建行為，官方教學文件明確說它輸出的是「編輯器需要的所有必要 CSS 類別與樣式」。
Edit元件解構出來的attributes跟setAttributes是這支元件的兩大支柱，前者讀取目前的資料值，後者是更新資料的唯一管道。官方文件也特別點出，Edit元件是唯一能透過setAttributes去修改這些 attributes 的角色，其他地方碰不到這個修改權限。
程式碼裡把文字內容改用RichText元件，而不是純文字段落，原因是RichText本身支援格式化文字（像是加粗、變色這類行內樣式），比純文字更貼近一般使用者對「編輯區塊」的期待。至於InspectorControls搭配PanelBody，則是把控制項放進右側設定面板的標準做法，這裡示範的ToggleControl只是@wordpress/components套件裡眾多控制項的其中一種，依需求也可以換成TextControl、SelectControl。使用者改動任何一個設定，setAttributes就會觸發重新渲染，畫面立刻反映最新結果，不需要手動刷新頁面。
save 與 render.php，兩種輸出方式的取捨
這是整篇技術深度最重要的一節，很多入門教學要嘛跳過、要嘛講得含糊。區塊的輸出方式分成兩種：靜態渲染跟動態渲染，兩者的取捨，決定了你的區塊適不適合這篇一直用的提示框情境，還是該換成需要即時資料的情境。
靜態渲染，是save.js回傳的 HTML 被完整序列化存進post_content，前台直接輸出這段存好的 HTML。WordPress 官方文件把這個特性講得很清楚：靜態渲染的區塊，會把區塊標記、attributes 跟輸出內容全部存進資料庫。它的好處是，萬一日後外掛被移除或停用，內容仍會留在資料庫裡，退化成一般的 HTML 區塊，不至於整段消失。提示框這種內容本身不隨時間變動的類型，選靜態渲染就足夠：
import { useBlockProps, RichText } from '@wordpress/block-editor';
export default function save( { attributes } ) {
const { message } = attributes;
const blockProps = useBlockProps.save();
return (
<div { ...blockProps }>
<RichText.Content tagName="p" value={ message } />
</div>
);
}Code language: JavaScript (javascript)動態渲染則相反，資料庫裡的區塊標記只存 attributes，不存 HTML 內容。官方文件描述它的區塊標記與相關 attributes 會被存進資料庫，但它的 HTML 輸出不會。每次載入頁面時，由render.php或render_callback即時產生輸出結果，適合內容會隨時間或系統狀態變動的情境，比如顯示當前年份、抓取最新一批文章這類需求。從 WordPress 6.1 開始，可以直接在 block.json 裡用render屬性指定路徑，不用再另外寫 PHP 掛勾函式。render.php裡可以取用$attributes、$content、$block這三個變數：
<?php
/**
* @var array $attributes 區塊在編輯器裡設定的屬性
* @var string $content 內層區塊輸出的內容
* @var WP_Block $block 區塊實例本身
*/
$message = $attributes['message'] ?? '';
?>
<div <?php echo get_block_wrapper_attributes(); ?>>
<p><?php echo esc_html( $message ); ?></p>
</div>Code language: PHP (php)save.js回傳的 HTML 結構，必須跟資料庫裡實際存的內容完全一致，兜不起來就會出現「區塊驗證錯誤」。官方教學文件說明這在開發過程中是很常見、也很正常的狀況，不代表區塊真的壞掉了，用編輯器提供的「嘗試復原區塊」（Attempt Block Recovery）就能處理，通常是改了save.js的邏輯，卻忘了同步更新舊有內容所導致。一個區塊也可以同時具備兩種機制，靜態存內容當備援、動態即時增強前台輸出，但這是進階用法，不是每個區塊都需要走到這一步。
在 PHP 端註冊區塊，讓編輯器認得這個新類型
鷹架工具建出來的外掛主檔，其實已經內建了register_block_type()的呼叫，只是很多人打開看到就直接跳過，不知道那段程式碼在做什麼。最基本的寫法長這樣：
<?php
function pongo_example_highlight_box_block_init() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'pongo_example_highlight_box_block_init' );Code language: PHP (php)這段程式碼掛在init這個動作鉤子上，路徑指向打包後的build資料夾，而不是src，因為build裡的才是真正可以被讀取的版本。register_block_type()讀取指定資料夾裡的 block.json，同時完成伺服器端與客戶端兩邊的註冊，而不是各自分開處理。
為什麼一定要在伺服器端註冊，不能只在 JavaScript 裡註冊？WordPress 官方文件對這點講得很直接，業界最佳實踐強烈建議同時在伺服器端與客戶端註冊區塊，這種雙重註冊，是動態渲染、區塊的 supports 樣式套用（跟 theme.json 整合）、區塊目錄收錄這類功能能不能正常運作的關鍵，少了伺服器端註冊，這些功能全部會失效。換句話說，只在客戶端註冊，區塊看起來能用，但背後一整批仰賴伺服器知道「這個區塊存在」的功能都會失效。
WordPress 6.7 之後多了wp_register_block_metadata_collection()，6.8 之後又多了wp_register_block_types_from_metadata_collection()，可以一次讀取整批區塊的 metadata 清單，再逐一註冊，對同時管理多個區塊的外掛來說，效能會比逐一讀取多個 block.json 檔案更好。不過如果只是單一區塊的外掛，像這篇的提示框範例，用最基本的register_block_type( __DIR__ . '/build' )就已經足夠，不必為了追新寫法而增加不必要的複雜度。
建置指令跑完之後，區塊出現在插入器的位置
理解跟填空做完之後，剩下的就是兩個動手指令，以及一個確認「完成了沒有」的明確判斷點。開發過程中執行npm run start，官方教學文件說明它會啟動一個開發伺服器，監看src/資料夾，只要偵測到程式碼變動就自動重新打包，不需要每改一次就手動重跑指令。
等到確定開發完成、準備部署上線之前，改執行npm run build。官方文件形容這個指令會「最佳化你的程式碼，讓它變成正式上線可用的版本」，跟npm run start的即時監看用途不一樣，兩者分工要記清楚，別在正式環境還跑著開發模式的指令。
打包完成、外掛啟用之後，回到編輯器用插入器搜尋區塊名稱，或瀏覽先前設定的分類，應該就能找到並插入這個區塊。確認方式有幾個層次：先看插入後編輯器畫面顯示得對不對，再存檔看前台輸出是否符合預期，最後切到程式碼編輯器，檢查儲存進資料庫的實際 HTML 結構，跟你原本設計的 save.js 輸出是不是一致。
另外，鷹架工具生成的檔案裡常常會留一些用不到的樣式檔或範例程式碼，官方教學文件也在最後步驟提醒，記得清乾淨，包括移除對應的 import，避免這些殘留內容混進正式版本、造成日後維護上的困惑。
不想寫 JavaScript，ACF 區塊是另一條路
研究這個主題，很可能會撞見另一條常被拿來比較的路，也就是用 Advanced Custom Fields 做區塊，跟前面一路走的原生開發是兩種不同定位，值得弄清楚彼此的差異，以及什麼情況下另一條路可能更適合。
Advanced Custom Fields 是國際上廣泛使用的 WordPress 客製欄位外掛，其付費版提供「ACF 區塊」功能，讓開發者用 PHP 樣板搭配欄位群組去產生區塊畫面，完全不需要寫 JavaScript 或 React。對已經熟悉 PHP、但不熟悉 JavaScript 生態系的開發者來說，這條路的上手門檻明顯低不少，不用先弄懂前面提過的 useBlockProps、attributes 序列化這些概念，就能做出一個能在編輯器裡填欄位的區塊。
這篇教的原生方式，優勢則在於編輯器內的即時互動體驗、跟核心區塊功能的整合深度，以及長期不依賴第三方外掛的穩定性。兩條路不互斥，同一個網站完全可以視需求混用，比較複雜、互動性高的區塊走原生開發，比較單純、以填欄位為主的區塊交給 ACF 處理，這裡不做誰更好的定論，只交代分工讓你自己判斷。
區塊系統正在往 AI 可操作的方向擴充
這篇教的技術現在還值得學嗎？答案是肯定的，而且 WordPress 核心近期的發展方向，反而讓這套知識往外延伸出新的用途。WordPress 6.9 推出了 Abilities API，讓外掛能把自己的功能註冊成標準化、機器可讀的「能力」，這是伺服器端、以 PHP 實作的介面。
到了 2026 年 5 月發布的 WordPress 7.0，進一步推出了客戶端（JavaScript）版本的 Abilities API，可以用來實作瀏覽、插入區塊這類客戶端操作。WordPress 核心開發部落格的文章說明得很直接：這項工作，對整合瀏覽器端的 AI 代理與擴充功能、以及 WebMCP 來說是基礎建設，目的是讓 AI 助理與自動化工具，能透過一套共通介面跟 WordPress 互動。
對正在學這套技術的你來說，這代表的意義是，自己開發出來的區塊，未來有機會透過這套標準化介面，被 AI 工具識別跟操作，而不是一個註冊完就跟外界隔絕的獨立功能。這是一個新的擴充方向，不是本文要教的操作範圍，有興趣的話值得再深入研究，但先把區塊本身的註冊機制搞懂，才有辦法接上後面這些新工具。
技術本身還在往前走，自訂區塊要面對的介面跟工具或許幾年後又不一樣，但把一個功能包成一個可以重複插入、可以被系統認得的區塊，這套底層邏輯不會因此過時。從最簡單的提示框開始練手，把 block.json、edit.js 跟 save.js 之間怎麼傳資料的邏輯搞懂之後，不管接下來要做的是需要拉即時資料的動態區塊，還是給某個專案量身訂做的內容元件，都是同一套機制的延伸。多數人真正過不去的，從來不是程式碼難寫，而是不知道每個檔案在整個機制裡扮演什麼角色，那個部分自己動手做過一次，就通了。