WordPress Site Health 重大錯誤排查｜Recovery Mode、PHP log 與外掛隔離

WordPress 後台的「網站健康狀態」如果突然出現重大錯誤，或管理員信箱收到 Recovery Mode 連結，第一反應通常會想把外掛全部停掉。這樣做有時可以讓網站恢復，但也很容易把真正的故障證據洗掉，之後只能憑印象猜是哪一個外掛、哪一次更新或哪段 PHP 程式造成。

我比較推薦把它當成一次小型事故處理：先保留證據，再縮小範圍，最後才做可回滾的變更。這份筆記整理的是 UCAMC 會採用的 WordPress Site Health 排查流程，目標不是追求一次就猜中，而是讓每一步都有觀察、變更、驗證與回復紀錄。

先判斷錯誤是「後台警告」還是「實際功能故障」

Site Health 的紅色提示有時是環境建議，有時是實際故障。處理前先把現象分層：

層級	常見訊號	第一個動作
後台健康檢查警告	Site Health 顯示 critical issue	截圖並記錄錯誤文字
Recovery Mode	WordPress 寄出故障外掛或主題提示	保存信件內容與時間
前台白畫面或 500	訪客看到錯誤頁	先查 HTTP status 與 error log
REST API 失敗	編輯器、區塊或外掛儲存失敗	查 `/wp-json/` 與 Network 回應
排程或背景任務失敗	備份、同步、訂單通知異常	查 cron、queue、外掛 log

這一步可以避免把所有問題都當成「外掛壞掉」。有些錯誤其實是 PHP 版本、記憶體限制、檔案權限、快取殘留、REST API 被 WAF 阻擋，或主題 template 內的 fatal error。

先保存可回放的錯誤證據

在改任何設定前，我會先建立一筆事件紀錄。最少要留下：

[observe] wordpress site health critical issue
site: example.com
observed at: 2026-08-12 09:10 +08:00
symptom:
  Site Health shows a critical PHP error
admin url:
  /wp-admin/site-health.php
public route checked:
  /
  /wp-json/
recent change:
  plugin update or PHP version change if known

如果可以連到伺服器，接著查錯誤紀錄。不同主機位置不同，但常見線索包含 PHP-FPM log、web server error log、WordPress debug log 或主機控制台的 error log。

# WordPress debug log，實際路徑依站台而定
wp-content/debug.log

# 常見主機 log 位置，需依環境調整
/var/log/nginx/error.log
/var/log/apache2/error.log
/var/log/php*-fpm.log

紀錄 log 時不要只貼最後一行。最好保留錯誤時間前後數十行，因為 fatal error 前面常會有 deprecation、autoload、permission 或外掛初始化順序的提示。

用 WP-CLI 先讀狀態，不急著停用

如果主機支援 WP-CLI，先讀現況比直接修改安全：

wp core version
wp option get siteurl
wp option get home
wp plugin list \
  --fields=name,status,update,version,update_version \
  --format=table
wp theme list \
  --fields=name,status,version,update \
  --format=table

接著確認 Site Health 相關測試是否指出 REST API、loopback request 或 background updates 失敗。這類問題可能不是某一個外掛的 fatal error，而是網路、SSL、DNS、WAF、Basic Auth、快取或主機限制造成。

wp transient delete --all
wp cache flush
wp cron event list --fields=hook,next_run,status --format=table

快取清除只能當作觀察手段，不要把它當成修復結論。清完快取後若錯誤消失，仍然要記錄「哪一層快取、清除時間、清除後驗證 URL」，否則下一次又會變成不可追蹤的偶發事件。

外掛隔離要一次一個變更，並保留回滾路徑

如果 log 指向某個外掛，先確認它是否真的啟用、最近是否更新、是否有相依外掛。然後用一次一個變更的方式隔離：

# 只停用疑似外掛，不要一口氣停用全部
wp plugin deactivate suspect-plugin

# 驗證前台與 REST API
curl -I https://example.com/
curl -I https://example.com/wp-json/

# 若不是它造成，立即恢復
wp plugin activate suspect-plugin

如果後台完全進不去，也可以用檔案層級暫時改名外掛資料夾，但這應該被視為 emergency 操作，必須記錄原始名稱、修改時間與恢復方式。

[change] isolate plugin
plugin: suspect-plugin
method: wp plugin deactivate suspect-plugin
reason: fatal error mentions plugin file path
rollback:
  wp plugin activate suspect-plugin

不要在未驗證前連續停用多個外掛、換主題、升級 PHP、清資料表。連續變更雖然可能讓網站恢復，但會讓根因追蹤變得非常困難。

PHP 版本與記憶體限制也要一起看

Site Health 的重大錯誤常見於 PHP 版本切換後：舊外掛使用了不相容語法、新版 PHP 將 warning 放大，或記憶體限制不足讓批次任務中斷。至少確認：

php -v
wp eval 'echo PHP_VERSION . PHP_EOL;'
wp eval 'echo WP_MEMORY_LIMIT . PHP_EOL;'
wp option get active_plugins --format=json

如果錯誤發生在主機自動升級 PHP 後，回滾 PHP 版本可能是短期止血，但不應該當成長期解法。紀錄要寫清楚：回滾到哪個版本、哪個外掛不相容、預計何時更新或替換。

驗證要涵蓋前台、後台與 API

修復後不要只看首頁能不能打開。至少做一輪 smoke test：

驗證項目	建議檢查
前台首頁	HTTP 200、主要 CSS/JS 載入
代表性文章或產品頁	內容正常、圖片正常
`/wp-json/`	HTTP 200 或合理 JSON
後台 Site Health	critical issue 是否消失或變少
編輯器	可開啟文章、可儲存草稿
表單 / 搜尋 / 會員功能	依站台關鍵功能測試
error log	修復後是否仍出現同一個 fatal error

可以把結果寫成簡短紀錄：

[verify] after plugin isolation
homepage: 200
/wp-json/: 200 application/json
admin editor: draft save ok
site health: no repeated fatal error
error log window:
  no matching fatal error after 09:42 +08:00

什麼時候不要繼續自動修？

有幾種情況我會停在紀錄與建議，不會讓自動化流程繼續改：

錯誤牽涉付款、會員、訂單或個資流程。
需要修改正式環境機密、資料庫帳密或第三方 API token。
需要刪除大量外掛、資料表或媒體檔案。
外掛停用會讓前台缺少重要商業功能。
根因可能是主機資安事件或檔案被竄改。

這些情境需要人工決策。自動化 Agent 可以把證據整理好、列出最小風險修復路徑，但不應該自行做不可逆操作。

我會保留的維護紀錄模板

[wordpress-site-health-incident]
date:
site:
symptom:
  Site Health / Recovery Mode / frontend 500 / REST API error
first observed by:
recent changes:
  plugin update:
  theme change:
  PHP version change:
  hosting change:
logs:
  file:
  time window:
  key error:
suspected layer:
  plugin / theme / PHP / cache / WAF / hosting / database
change made:
rollback path:
verification:
  homepage:
  representative page:
  /wp-json/:
  wp-admin editor:
  Site Health:
  error log after fix:
next action:

這份模板的價值不在於格式，而是讓每一次 WordPress 故障都能變成可搜尋的運維知識。下次 Site Health 再出現紅色警示，就不用從頭猜測，而能沿著已驗證的紀錄判斷：是哪一層、做過哪些變更、哪個驗證結果才算真正恢復。

WordPress Site Health 顯示重大錯誤時：先保留證據，再排查外掛與 PHP 問題