04 部署與基礎設施
04 Next.js + Headless WordPress 更新策略
說明多個 Next.js + Headless WordPress 專案目前為什麼採用 time-based ISR。
作者：Percy
最後整理：2026-04-11
敏感資料交付提醒：本文件中的 05-environment-variables 指 05-environment-variables_環境變數與金鑰；該文件含 env value / secret 線索，僅做本地交付，不做雲端交付。
多個 Next.js + Headless WordPress 專案目前採用相近的更新方式：time-based ISR，加上 revalidate: 1 或接近的短週期設定。
這份文件不是逐站 debug 手冊。它只說明為什麼目前沒有全面改成 on-demand revalidate、哪些站適用這個判斷，以及接手時最容易誤會的地方。
這裡不處理
- 不取代單一專案 README
- 不列 env value 或平台權限
- 不提供逐站 debug 手順
先去哪裡
| 情境 | 先看哪裡 |
|---|---|
| 想知道為什麼內容不是即時更新 | 看這份 |
| 想知道某站實際 cache / deploy 排查步驟 | 先回該 repo README，再看 04-deployment |
| 想知道某個 revalidate key 或 env 值 | 回 05-environment-variables |
適用範圍
適用：
mattertintrongonnapresoteaxinyishengnicegingermatterkits/app1
不適用或僅部分適用：
hanpoo-ecommerce- 此專案是 React + Vite，不屬於 Next.js ISR 模式
Chlitina-Refining- 此專案是 Next.js Pages Router 靜態輸出，請改看 靜態輸出部署注意事項
KindShare-Exocare- 此專案是 Next.js Pages Router 靜態輸出，請改看 靜態輸出部署注意事項
matterkits/app2- 目前是骨架型 app，不應假設已有同樣更新策略
目前策略
選這條路的原因不是因為不知道 on-demand revalidate，而是為了：
- 維持多專案更新模型一致
- 降低交接成本
- 避免每站都額外維護一套 webhook 對應規則
最容易誤判的地方
revalidate: 1不是即時同步- 它不代表每秒主動重建整站
- 它比較接近 stale-while-revalidate
- CMS 一存檔，不代表使用者當下就一定看到最新內容
為什麼不全面改 on-demand
on-demand revalidate 很精準，但需要額外維護：
- Next.js revalidate API
- secret 驗證
- WordPress webhook
- 內容事件對應頁面規則
- 多 instance / cache 一致性策略
在多專案維護情境下，這些額外成本目前高於收益。
接手時先記住
- 先理解現況，不要一接手就把所有站改成 on-demand
- 遇到內容沒更新時，先分清楚是：
- CMS 沒發布
- GraphQL 沒更新
- ISR / revalidate 尚未生效
- webhook / cache / deploy 問題
- 這些專案的共通陷阱通常不是 React component 本身，而是：
- WordPress 內容事件
- GraphQL 資料一致性
- cache / revalidate 行為理解
之後可以怎麼演進
如果未來要優化，建議不是一次全面翻掉，而是：
- 先挑少數關鍵頁面試行 on-demand
- 保留 ISR 作為 fallback
- 等路徑與資料關聯整理清楚後，再逐步擴大
文件位置
這份文件主放在 04-infrastructure-and-deployment，因為它本質上是：
- 系統更新策略
- cache / ISR / deploy 行為說明
- 跨專案架構決策提醒
在 07-cms-content-operations 與 15-runbooks 只用一句話引用即可，不要重貼內容。