在台灣接案市場上，WordPress 案子有很高的比例是 WooCommerce，而 WooCommerce 這幾年正在經歷跟佈景主題一樣的轉變 — 從 PHP 範本與短代碼搬到區塊與 API。

兩套世界同時存在

先講清楚現況。WooCommerce 現在的前台有兩套實作並存：

兩套都還能用，新開的店預設會用新的。但網路上大部分中文教學寫的是舊的那一套，而那些做法在區塊結帳頁上完全無效，這一部要處理的就是這個落差。

用傳統佈景主題的經驗來理解

這個轉變其實跟我們前面講的完全同構：

• 傳統佈景主題改版面 → 覆蓋 single.php；WooCommerce 舊做法改商品頁 → 覆蓋 woocommerce/single-product.php
• 區塊佈景主題改版面 → 編 templates/single.html；WooCommerce 新做法改商品頁 → 編 single-product 這個區塊範本

實際上 WooCommerce 就提供了一整組區塊範本，跟主題的 templates/ 是同一套機制：

woocommerce/templates/templates/
├── archive-product.html
├── page-cart.html
├── page-checkout.html
├── order-confirmation.html
└── blockified/          # 全區塊化的版本

也就是說之前介紹區塊的內容在 WooCommerce 這邊直接適用，差別只在於那些區塊裡面裝的不是靜態內容，而是購物車、結帳這種帶狀態的互動元件。

真正的轉折點：Store API

如果只看到短代碼換成區塊那還只是換個外殼，真正改變開發方式的是 **Store API，**WooCommerce 提供了一組公開的 REST 端點，讓前端能直接操作購物車與結帳。實測一下你自己的站台（不用登入，這是公開端點）：

$ curl https://your-site.com/wp-json/wc/store/v1/

然後會出現多個端點：

/wc/store/v1/cart
/wc/store/v1/cart/add-item
/wc/store/v1/cart/remove-item
/wc/store/v1/cart/apply-coupon
/wc/store/v1/cart/select-shipping-rate
/wc/store/v1/cart/update-customer
/wc/store/v1/checkout
/wc/store/v1/products
/wc/store/v1/products/collection-data
…

看一下購物車端點回傳什麼：

$ curl https://your-site.com/wp-json/wc/store/v1/cart

billing_address, coupons, cross_sells, errors, extensions, fees,
has_calculated_shipping, items, items_count, items_weight, needs_payment,
needs_shipping, payment_methods, payment_requirements, shipping_address,
shipping_rates, totals

這就是新版購物車與結帳頁的資料來源，前端是 React，狀態存在瀏覽器裡，每個動作（改數量、套用折價券、選運送方式）都打一次 API 拿回完整的購物車狀態然後重繪畫面。整個結帳流程從「送出表單、整頁重載」變成「打 API 局部更新」。

注意 extensions 這個欄位，它是留給你放自訂資料的地方，之後提到資料流時會用到。

這對開發方式的三個影響

一、舊的 PHP hook 大部分失效

你熟悉的 woocommerce_checkout_fields 這類 filter 是用來改 PHP 產生的結帳表單，而區塊結帳頁的表單是 React 畫的，資料來自 Store API。用原本的 filter 區塊結帳頁不會有任何變化。

二、前後端要各做一次

以前加一個結帳欄位改 PHP 就結束了，現在你要讓欄位出現在 React 表單裡（前端）、也要讓它通過驗證並存進訂單（後端）。好消息是 WooCommerce 提供了 API 讓你一次註冊、兩邊生效，不用真的寫兩份。

三、擴充點變少了，但變乾淨了

舊做法你可以用 filter 改任何一段 HTML，自由度極高，代價是 WooCommerce 每次改版都可能弄壞你的客製。新做法的擴充點是明確定義的 API，能做的事變少，但升級時不會突然爆炸。

為什麼這個轉變對 AI 開發有利

這跟第二部講區塊佈景主題的理由是同一個，舊做法要 AI 改對它得知道你的主題覆蓋了哪些範本、哪個 hook 在哪個位置觸發、輸出的 HTML 長什麼樣，這些事散落在各處，增加 AI 開發時上下文遺失的風險。

新做法有明確的 API 邊界：註冊欄位有固定格式、金流整合有抽象類別要實作、資料有 schema。邊界明確的東西 AI 產出的正確率高很多，而你 review 的成本也低，因為你知道該檢查哪幾個點。

然而 WooCommerce 這幾年的 API 變動很快，AI 的訓練資料很可能停在舊版**，**它會很自信地給你 woocommerce_checkout_fields 的做法，因為網路上這種寫法最多，所以這一部的每一篇我都會把「AI 最可能給你的錯誤答案」跟「現在正確的做法」放在一起講。

這一部要走的路

接下來九篇的路線是這樣：

1. 先盤點 WooCommerce 有哪些區塊、對應到舊的什麼
2. 深入購物車與結帳的資料流，理解為什麼舊 hook 失效
3. 動手加一個自訂結帳欄位
4. 金流：先理解原理、再實作一個台灣的金流、最後讓它支援區塊結帳
5. 台灣電商必備的兩件事：電子發票與超商物流
6. 最後把這些客製收進外掛，處理相依與品質

下一篇我們先把 WooCommerce 的區塊仔細盤點，光是 WooCommerce 自己註冊的區塊就有一百多個，先知道有哪些積木之後才後再組裝時才知道要用哪些材料。

文章目錄：https://oberonlai.blog/category/2026-ithome/