UCAMC
← 回到 Blog
WordPress約 3 分鐘閱讀

WordPress REST API 健康檢查：不要等到編輯器壞掉才看 /wp-json/

Updated 2026/08/07UCAMC
分類WordPress網站經營自動化工作流
標籤#WordPress#REST API#WP-CLI#網站維運#故障排除
WordPress REST API 健康檢查儀表板與 curl 狀態確認畫面

WordPress REST API 平常不一定會被內容編輯注意到，但它一出問題，症狀常常不是「API 壞了」四個字，而是區塊編輯器無法儲存、外掛設定頁空白、前端表單送不出去，或自動化流程突然拿不到文章資料。這些問題如果只用「重新整理後台」或「清快取」處理，很容易把真正的失敗層級藏起來。

我會把 REST API 健康檢查當成網站維運的固定巡檢項目。它不需要每天做大規模掃描，但至少要有一份可重複的 runbook：出問題時先看哪幾個 endpoint、如何判斷是 WordPress 本身、登入權限、外掛、WAF/CDN、快取，還是瀏覽器端 JavaScript 錯誤。

先確認 /wp-json/ 回應是不是 JSON

第一步不要進後台亂停外掛，而是直接檢查公開 REST API root。最基本的 curl 應該同時留下 status、content-type 與下載大小：

curl -L -sS -o /dev/null \
  -w 'status=%{http_code} type=%{content_type} size=%{size_download}\n' \
  'https://www.example.com/wp-json/'

我會把結果分成幾種狀況：

  • 200 + application/json：REST API root 基本可讀，下一步看特定 route 或登入權限。
  • 301/302 後變成登入頁：可能被安全外掛、WAF 或規則導走。
  • 403：先查權限、安全外掛、伺服器規則與 CDN 防護。
  • 404：先查 permalink、rewrite、Nginx/Apache 規則或 WordPress 是否載入正確。
  • 200 但 text/html：最危險，因為看似成功，實際上可能是維護頁、登入頁或錯誤頁。

檢查紀錄不要只寫「API 正常」。比較有用的是：

[observe] REST API root
url: https://www.example.com/wp-json/
status: 200
content-type: application/json; charset=UTF-8
size: 18432
judgement:
  REST API root returns JSON. Continue with editor route,
  auth-sensitive requests, and browser Network errors.

用代表性 route 分辨是全站 API 壞掉，還是某個功能壞掉

/wp-json/ 只是入口，真正壞掉的可能是某個 namespace。可以接著檢查幾個低風險 endpoint：

curl -L -sS -o /dev/null \
  -w 'posts status=%{http_code} type=%{content_type} size=%{size_download}\n' \
  'https://www.example.com/wp-json/wp/v2/posts?per_page=1'

curl -L -sS -o /dev/null \
  -w 'types status=%{http_code} type=%{content_type} size=%{size_download}\n' \
  'https://www.example.com/wp-json/wp/v2/types'

如果 root 正常但 posts route 失敗，就要看是否被 REST permission、外掛 hook、custom post type、或某個 security rule 攔下。若只有登入後的 Gutenberg 儲存失敗，則公開 curl 可能完全正常，必須補上瀏覽器 Network 與登入狀態下的錯誤訊息。

區塊編輯器錯誤要看 Network，不要只看畫面訊息

區塊編輯器常見訊息像是「更新失敗」或「回應不是有效 JSON」，這些字不夠判斷問題。打開瀏覽器 DevTools 的 Network，篩選 wp-json 或 admin-ajax，至少記錄：

  • Request URL：是哪個 REST route。
  • Status code：401、403、500 還是 200。
  • Response preview：是 JSON、HTML、WAF 頁、PHP warning，還是空白。
  • Initiator：是 WordPress core、theme script，還是某個 plugin script。
  • Console：是否有 JavaScript error 讓請求根本沒送出。

如果 response body 前面出現 PHP warning，即使 status 是 200，Gutenberg 也可能判斷它不是合法 JSON。這時問題不一定在 REST API route，而是某個外掛、佈景主題或 PHP notice 把輸出污染了。

用 WP-CLI 補足 WordPress 層的狀態

curl 看到的是 HTTP 層，WP-CLI 可以協助確認 WordPress 內部狀態。不過 WP-CLI 是正式站變更工具，先用 observe 指令，不要一開始就 flush 或 deactivate。

# observe：確認 rewrite 與外掛狀態
wp rewrite list --format=table
wp plugin list --status=active
wp option get permalink_structure

# observe：列出 REST route，確認目標 namespace 是否存在
wp rest route list --format=table

有些主機環境沒有 wp rest route list，那就把它標記為「未驗證」，不要假裝已排除 route 註冊問題。維護紀錄應該保留這種限制：

[observe]
command: wp rest route list --format=table
result: command not available on this host
judgement:
  REST route registration was not verified via WP-CLI.
  Continue with HTTP endpoint checks and plugin isolation plan.

外掛隔離要先設計 rollback

REST API 問題常和安全外掛、快取外掛、會員外掛、表單外掛或自訂 REST hook 有關。但在正式站停用外掛前，先寫好 rollback 與驗證方式：

[change candidate]
action: deactivate security plugin temporarily
reason: REST API /wp/v2/posts returns 403 only after WAF headers
rollback: reactivate plugin immediately after route test
verify:
  - /wp-json/ returns JSON
  - editor save succeeds
  - frontend critical page still returns 200

如果沒有維護窗口、沒有備份、沒有權限確認，就不要把「停用外掛」當成第一個動作。可以先複製到 staging、或只調整外掛中針對 REST API 的 allowlist 規則，再用同一組 curl 和瀏覽器 Network 驗證。

不要忽略 CDN、WAF 和 cache header

REST API 不是只有 WordPress 決定。Cloudflare、主機 WAF、Nginx 規則、Basic Auth、反向代理、甚至頁面快取都可能改變 response。健康檢查最好把 header 也存下來：

curl -L -sS -D - -o /dev/null \
  'https://www.example.com/wp-json/'

重點不是把所有 header 都背下來，而是看：

  • 是否有 cf-cache-status、x-cache、x-vercel-cache 或主機快取標記。
  • 是否有 content-type: text/html 卻回 200。
  • 是否被加上奇怪的 redirect 或 security challenge。
  • 是否只在特定 User-Agent 或登入 cookie 下失敗。

如果你只在 WordPress 後台改設定，卻沒有比對 CDN/WAF 層，可能會把時間花在錯的地方。

一份可交接的 REST API 健康檢查紀錄

我會把最後紀錄整理成這樣：

[rest-api-healthcheck]
time: 2026-08-07 09:10 +0800
scope:
  - /wp-json/
  - /wp-json/wp/v2/posts?per_page=1
  - Gutenberg save request from browser Network

observations:
  - root returns 200 application/json
  - posts endpoint returns 403 with security plugin header
  - editor save request fails on the same namespace

judgement:
  problem is likely permission/security layer, not a global
  WordPress routing failure. Plugin/WAF rule should be isolated
  with rollback prepared.

next verification:
  - staging plugin rule change
  - repeat curl status/content-type/size checks
  - browser editor save test

這種紀錄的價值在於，它把「看到什麼」、「怎麼判斷」、「下一步怎麼驗證」放在同一份筆記裡。下一位維護者不需要重新猜是 permalink、外掛、PHP warning、CDN 還是登入權限問題。

小結：REST API 巡檢是網站經營的一部分

WordPress REST API 不是只有開發者才需要管。它支撐內容編輯、外掛設定、前端互動、行銷工具、自動化匯出與很多無頭式整合。越是長期經營的網站，越需要把 /wp-json/ 健康狀態納入固定檢查，而不是等到編輯器不能存文章才臨時處理。

UCAMC 這類技術內容站會把這種檢查整理成公開文章與內部維護筆記：公開文章保留可學習的方法，內部筆記保留實際 URL、時間、輸出與 rollback。兩者目的相同——讓網站維護從「靠印象修」變成「有證據、有判斷、有回復路徑」。