2026.09.05

WordPress 出現 500 錯誤時，如何從 PHP 錯誤日誌定位外掛或佈景主題問題

網站剛完成 WordPress 核心、外掛或佈景主題更新，前台突然回傳 500 Internal Server Error，部分頁面甚至只剩白畫面。這類問題通常不是重新整理就會消失；第一個目標是確認影響範圍，第二個目標則是從 PHP 錯誤日誌找出真正出錯的元件。以下流程適合公司維運情境，請優先在測試環境或可控時段操作。

先確認影響範圍與最近變更

用無痕視窗測試首頁、幾個一般頁面、登入頁與後台。
確認是整站 500，還是只有特定網址、表單或購物流程失敗。
記錄錯誤開始時間、受影響網址、最近更新的外掛或佈景主題。
先查看主機商提供的 PHP error log；若有監控，也比對 500 回應數是否突然增加。

若只有某個功能失效，先不要停用全部外掛。若前台與後台都無法使用，則要先保留目前狀態與日誌，再進行縮小範圍。更新前若已建立可用備份，可參考WordPress 備份與還原實務中的驗證與回復觀念。

在可控時段開啟 WordPress 除錯

不要在尖峰時段直接於正式站長時間開啟除錯。先通知相關人員，確認有備份，並限制測試範圍。編輯網站根目錄的 wp-config.php；若檔案已有相同常數，請修改原本設定，不要重複加入。

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

這樣會把錯誤寫入 wp-content/debug.log，但不會直接顯示給訪客。開啟後，以無痕視窗重現一次問題，再立即讀取最新紀錄。官方說明可參考WordPress 除錯文件。

從 debug.log 辨識真正的出錯位置

tail -n 80 wp-content/debug.log
grep -n "PHP Fatal error" wp-content/debug.log | tail -n 10

預期會看到類似以下內容：

PHP Fatal error:  Uncaught Error: Call to undefined function ...
in /var/www/html/wp-content/plugins/example-plugin/includes/order.php:142

先看三個重點：錯誤類型是否為 PHP Fatal error、完整檔案路徑，以及最後的行號。路徑若包含 wp-content/plugins/，通常可先懷疑該外掛；若包含 wp-content/themes/，則檢查目前使用的佈景主題。行號是發生錯誤的位置，不一定代表根本原因，但能快速縮小檢查範圍。也要注意同一時間可能有多筆錯誤，請以重現問題後新增的紀錄為主。

不要把 debug.log 公開。它可能包含檔案路徑、網站設定或請求資料。確認內容後，限制檔案權限，並避免在文章、工單或公開聊天室貼出完整日誌。

用 WP-CLI 或單一停用方式縮小範圍

能登入主機時，先列出目前啟用的外掛：

wp plugin list --status=active

預期會列出外掛名稱、狀態與版本。依照日誌指向的外掛，只停用該項，不要一開始使用停用全部外掛：

wp plugin deactivate example-plugin

成功時通常會看到 Plugin 'example-plugin' deactivated.。接著重新測試原本失敗的網址，並再讀一次日誌。如果錯誤消失，問題範圍就已縮小到該外掛；先保留版本、錯誤行號與測試結果，再決定回復版本、等待相容版本或交由開發者修正。WP-CLI 指令細節可參考官方外掛指令文件。

若日誌路徑指向佈景主題，可在測試環境或低流量時段切換到已安裝的預設佈景主題：

wp theme activate twentytwentyfour

預期會顯示佈景主題已啟用。切換後再次測試；若 500 消失，就檢查原佈景主題最近的程式碼或版本相容性。切換佈景主題可能影響版面與小工具，請先記錄原本佈景主題名稱，並在驗證後切回。

無法登入後台時的緊急處理

檔案重新命名只能作為無法登入後台、又必須先恢復服務的緊急手段。透過 SSH 或檔案管理器將疑似外掛目錄重新命名，例如：

mv wp-content/plugins/example-plugin wp-content/plugins/example-plugin.off

重新測試網站後，若恢復正常，請不要把這個狀態當成完成。保留原目錄名稱與時間紀錄，確認備份，接著以正式方式停用、回復或更新外掛。問題確認後也要把目錄名稱恢復，避免日後誤判檔案遺失。這種作法不適合拿來一次停用大量元件，否則會失去判斷依據。

回復、驗證與關閉除錯

若更新造成問題，從已驗證的備份或上一個可用版本回復，不要只回復資料庫而遺漏外掛檔案。
依序測試首頁、主要頁面、登入、表單、排程與第三方整合。
確認 PHP error log 不再出現新的 Fatal error，並觀察一段時間的 500 監控數據。
完成確認後，將 WP_DEBUG、WP_DEBUG_LOG 設為 false，或移除臨時設定；同時保持 WP_DEBUG_DISPLAY 為 false。

後續更新可搭配WordPress 外掛更新實務，先在測試環境驗證，再安排正式站更新，降低再次出現白畫面的機率。