第一次想手刻區塊主題的人，常常被網路上那些動輒十幾個資料夾的範例嚇退，以為一個 FSE 主題非得備齊 templates、parts、patterns、styles、assets 才跑得起來。實際上，要讓 WordPress 認得你的主題、而且能在站台編輯器裡開起來，需要的檔案少到會讓你意外。

這篇要帶你只用最精簡的幾個檔案，從一個空資料夾手刻出一個能啟用的區塊主題，並說清楚每個檔案的最小內容、哪些是必需、哪些是可選、為什麼可選。不靠 Create Block Theme 外掛、不複製別人的 starter theme，純手寫，把骨架徹底看懂。

區塊主題跟傳統主題在檔案結構上差在哪

兩者最大的差別，是版面從 PHP 模板換成了 HTML 模板加區塊語法。傳統主題（也就是俗稱的古典主題）靠 index.php、single.php、header.php 這些 PHP 檔，配合 Template Hierarchy 來決定每種頁面長什麼樣；版面邏輯跟 PHP 程式碼混在同一個檔案裡。

區塊主題保留了 Template Hierarchy 的概念，但把所有 .php 模板換成了 .html 模板，而且這些 HTML 檔只接受區塊語法，不能直接寫 PHP 邏輯。原因是站台編輯器要能讀懂這個頁面、知道用哪個區塊去渲染與編輯，所以版面必須以區塊的形式描述。

另一個差別是樣式的集中化。傳統主題的顏色、字級、間距散落在各個 CSS 檔裡；區塊主題則把這些設定收進單一的 theme.json，由 WordPress 統一管理顏色、字體、間距與版面寬度。這也是為什麼區塊主題的 style.css 通常幾乎是空的，只留下標頭。

實務上還有一個常被忽略的差異：區塊主題的 functions.php 是可選的。傳統主題幾乎一定要靠 functions.php 來掛載樣式表、註冊選單、宣告主題支援；區塊主題的這些工作大多由 theme.json 接手，因此一個最小主題完全可以沒有 functions.php。

一個能啟用的區塊主題最少要哪幾個檔案

讓 WordPress 認得並啟用一個區塊主題，硬性必需的只有兩個檔案：根目錄的 style.css，以及 templates/ 資料夾裡的 index.html。theme.json 不是強制的，但強烈建議放，少了它你幾乎無法控制全站樣式與版面。

把這個最小骨架攤開來看，結構長這樣：

把這個資料夾放進 wp-content/themes/ 底下，到後台「外觀 → 佈景主題」就會看到它，能啟用。沒有 screenshot.png 只是縮圖空白，不影響啟用；沒有 functions.php、parts/、patterns/ 也完全跑得起來。

下表把這幾個檔案的角色與必要性整理清楚：

從這裡開始，後面三節就逐一把必需的三個檔案內容寫出來。

style.css 的標頭欄位該怎麼寫

style.css 在區塊主題裡的唯一硬性任務，是用檔案開頭的註解標頭告訴 WordPress「這是一個主題、它叫什麼名字」。樣式可以一行都不寫，但標頭一定要有，否則後台根本不會把這個資料夾當成主題列出來。

一個最小可用的標頭只需要幾個欄位：

/*
Theme Name: My Theme
Theme URI: 
Author: 你的名字
Description: 一個手刻的極簡 FSE 區塊主題
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.6
Requires PHP: 7.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
*/

真正不能省的是 Theme Name，這是後台辨識與顯示主題名稱的依據。Text Domain 建議跟資料夾名稱一致，之後做多語系翻譯會用到。Requires at least 標到 6.0 以上，因為站台編輯器要 WordPress 6.0 才完整支援區塊主題。

值得注意的是，區塊主題的顏色與字體已經交給 theme.json 管，所以 style.css 標頭底下通常是空的。你當然可以在這裡補一些 theme.json 涵蓋不到的細部 CSS，但那是後話，最小骨架階段留空即可。標頭格式錯誤（例如漏掉 Theme Name 或註解符號寫錯）是新手最常見的「主題沒出現在列表」原因，寫完先檢查這段。

theme.json 的最小骨架要放哪些設定

theme.json 是區塊主題的設定中樞，少了它主題仍能啟用，但你會失去對顏色、字體、間距、版面寬度的集中控制權，編輯器也少掉大半可調項目。一個最小但實用的 theme.json 大致長這樣：

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "660px",
      "wideSize": "1000px"
    },
    "color": {
      "palette": [
        { "slug": "base", "color": "#ffffff", "name": "底色" },
        { "slug": "contrast", "color": "#111111", "name": "對比色" },
        { "slug": "accent", "color": "#00838f", "name": "強調色" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    }
  },
  "templateParts": [
    { "name": "header", "area": "header", "title": "頁首" },
    { "name": "footer", "area": "footer", "title": "頁尾" }
  ]
}

逐段拆解這份骨架的關鍵欄位：

• $schema：指向官方 schema，讓編輯器（VS Code 之類）能自動補全與提示欄位，純為開發方便，不影響執行。
• version：目前最新是第 3 版，從 WordPress 6.6 起導入。舊版（第 2 版）仍向下相容，但新功能只在最新版開發，新主題直接用第 3 版即可。
• settings：定義使用者能調整哪些選項、以及預設的顏色與字級。這裡放了 appearanceTools: true，它是一個總開關，一次打開邊框、連結顏色、間距、行高等一整批進階控制項，省去逐項宣告。
• settings.layout：contentSize 是內容的預設寬度，wideSize 是「寬版對齊」時的寬度，這兩個值決定全站版面的基準。
• settings.color.palette：定義調色盤。每一個顏色都會被 WordPress 轉成 CSS 自訂屬性，例如 accent 會變成 --wp--preset--color--accent，可以在 styles 區塊或自己的 CSS 裡直接引用。
• styles：把上面定義的設定真正套用到主題，例如把整站背景設成底色、文字設成對比色。settings 是「提供哪些選項」，styles 是「實際套用哪些值」，兩者分工要分清楚。
• templateParts：宣告 parts/ 資料夾裡的組件屬於哪個區域（header／footer），編輯器才知道把它們歸到正確的版面位置。

settings 與 styles 的差別是新手最常混淆的點。簡單記：settings 管「給不給使用者調、預設值是什麼」，styles 管「主題本身實際長什麼樣」。把顏色寫進 palette 只是讓它出現在選色盤，真要讓背景變色，得在 styles 裡引用那個變數。

templates 與 parts 怎麼用區塊語法手刻

模板檔的內容不是普通 HTML，而是區塊標記（block markup）。每個區塊用 <!-- wp:區塊名稱 --> 開頭、<!-- /wp:區塊名稱 --> 結尾的特殊註解包起來，WordPress 解析這些註解來知道該渲染哪個區塊。手刻時最容易出錯的，就是漏掉結尾註解或寫錯區塊名稱。

先看必需的 templates/index.html，這是沒有其他模板匹配時的後備模板，一個最小版本只要把頁首、內容、頁尾三段串起來：

<!-- wp:template-part {"slug":"header","area":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer","tagName":"footer"} /-->

這裡的 wp:template-part 是自閉合區塊（結尾是 /-->），它去抓 parts/ 裡對應 slug 的組件。中間用一個 wp:group 包住 wp:post-content，layout.type 設成 constrained 代表內容會被約束在 theme.json 裡定的 contentSize 寬度內。

接著補上 parts/header.html 與 parts/footer.html。頁首放網站標題就好：

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:site-title /-->
</div>
<!-- /wp:group -->

頁尾放一行版權字樣：

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:paragraph -->
  <p>© 你的網站名稱</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

手刻區塊語法有兩個訣竅可以降低出錯率。第一、不確定某個區塊的正確註解寫法時，先在站台編輯器裡用滑鼠拉出那個區塊，切到程式碼編輯檢視，把產生的標記複製出來貼進 HTML 檔，比憑記憶手打可靠。第二、區塊註解裡的 JSON 屬性（例如 {"layout":{"type":"constrained"}}）必須是合法 JSON，逗號或引號錯一個，整個區塊就會在編輯器裡顯示成「此區塊發生錯誤」。

到這一步，style.css、theme.json、templates/index.html、parts/header.html、parts/footer.html 五個檔案就構成一個能啟用、能正常顯示頁首內容頁尾的完整骨架。

functions.php、patterns、styles 這些可選檔案什麼時候才加

可選檔案的共通原則是「有需求才加」，不要一開始就把資料夾全部建好放著空轉。骨架能跑之後，依照下面的時機逐步擴充就好。

functions.php：當你需要寫 theme.json 涵蓋不到的功能時才加，例如註冊自訂的區塊樣式變體、掛載額外的編輯器腳本、或用 PHP 過濾 theme.json 的值。如果你只是要改顏色、字體、版面，根本用不到它。

patterns/：當你想把一段排好的版型存起來重複使用時才加。版型用 PHP 檔定義，每個檔案開頭寫一段註解標頭宣告名稱、描述與分類，底下接區塊標記。版型的好處之一是內容可以走翻譯流程，這也是讓區塊主題支援多語系的標準做法——因為 HTML 模板裡的文字本身是不可翻譯的，要翻譯就得改用 PHP 版型。

styles/：當你想提供「樣式變體」讓使用者一鍵切換整體外觀（例如淺色、深色、不同色系）時才加。每個變體是一個獨立的 JSON 檔，結構跟 theme.json 一樣，放進 styles/ 後就會出現在編輯器的樣式面板裡。

其他常見模板：index.html 是後備，但你通常會想針對不同頁面類型補上專屬模板，常見的有 single.html（單篇文章）、page.html（靜態頁面）、archive.html（彙整頁，如分類或標籤）、search.html（搜尋結果）、404.html（錯誤頁）。這些都放在 templates/ 裡，缺哪個 WordPress 就自動回退到 index.html，所以可以一個一個慢慢補，不必一次到位。

如果你的主題之後會牽涉到商品或收款相關頁面，那通常是另外裝 WooCommerce 之類的外掛、由外掛提供對應模板與區塊，主題端只需要保留相容的版面容器即可，不需要在這個最小骨架裡自己處理任何結帳邏輯。

主題手刻完怎麼啟用與排查常見問題

把主題資料夾放進 wp-content/themes/ 後，到後台「外觀 → 佈景主題」按啟用，再到「外觀 → 編輯器」就能進站台編輯器調整模板。如果這兩步任何一步卡住，下面幾個是手刻主題最常見的狀況與對應排查方向。

主題沒出現在列表：九成是 style.css 標頭有問題。檢查檔案是否真的叫 style.css、放在主題資料夾根目錄、開頭的註解格式正確、Theme Name 欄位存在且不為空。標頭少了或註解符號 /* */ 寫錯，WordPress 就不會把這個資料夾當主題。

啟用後「外觀」沒有「編輯器」選項：代表 WordPress 沒把它當成區塊主題。最常見原因是少了 templates/index.html——這個檔案是 WordPress 判定「區塊主題」的關鍵之一。確認 templates/ 資料夾拼字正確、index.html 確實在裡面。

頁面一片空白或只顯示部分內容：通常是某個模板或組件的區塊語法壞了。優先檢查 template-part 的 slug 有沒有對到 parts/ 裡真實存在的檔名，以及區塊註解的開頭與結尾是否成對、JSON 屬性是否合法。

編輯器裡某個區塊顯示「發生錯誤」：多半是該區塊註解裡的 JSON 寫壞了，例如多一個逗號、引號沒成對、或區塊名稱拼錯。把那段區塊標記單獨抓出來檢查 JSON，或乾脆在編輯器重拉一次再複製正確標記回來。

手刻一個極簡區塊主題的價值，不在於它能直接拿去做正式網站，而在於跑完這一輪你會清楚知道每一個檔案在替你做什麼、哪些是地基、哪些是裝潢。掌握了這個最小骨架，之後不管是擴充模板、接手別人的主題、還是讀官方文件，你都不會再被那一長串資料夾嚇到。下一步，挑一個你最常用到的頁面類型，幫它補上專屬模板，讓骨架慢慢長成你真正要的主題。