解決 WordPress 區塊編輯器無法載入的問題

多數情況下，WordPress 區塊編輯器無法載入其實是 JavaScript 錯誤造成的——某個外掛或佈景主題的一段損毀指令碼會中斷整個 React 應用程式，導致編輯器永遠無法完成算繪。開啟瀏覽器的開發者主控台（F12，Mac 上是 Cmd+Option+I），重新載入編輯畫面，然後讀取那則紅色錯誤訊息。它幾乎一定會指出拋出錯誤的檔案。那一行就能告訴你該停用哪個外掛，通常五分鐘內你就能回去繼續寫作。網路上最常見的三種建議是重新安裝 WordPress、調高 PHP 記憶體上限，以及改用傳統編輯器（Classic Editor），而這三種做法通常都是錯的。

編輯器為什麼會這樣壞掉

區塊編輯器（Gutenberg）是一個單頁式 React 應用程式，執行於 wp-admin/post.php 與 post-new.php 之中。WordPress 會排入佇列一整疊指令碼套件——wp-blocks、wp-element、wp-editor、wp-edit-post——並透過 wp.domReady() 啟動整個應用程式。JavaScript 一遇到第一個未被攔截的例外就會停止執行。因此，只要任何一個已排入佇列的指令碼在編輯器初始化期間拋出錯誤，其後的一切都會跟著陣亡。你精心撰寫的文章編輯區就會崩塌成一片空白的白色面板，或顯示「編輯器發生非預期的錯誤」訊息。

WordPress 預設還會把後台指令碼串接成較少的請求。這表示某個外掛損毀的 JS 可能拖垮同一個組合包中載入的其他不相干指令碼，這也是為什麼光看行為往往看不出真正的元凶。但主控台看得出來。

第二種故障模式看起來不一樣：編輯器載入了，但儲存時卻拋出「更新失敗。回應不是有效的 JSON 回應。」這不是 JavaScript 的問題。編輯器透過位於 /wp-json/wp/v2/ 的 REST API 溝通，並預期收到乾淨的 JSON。如果某個外掛或你佈景主題的 functions.php 在 JSON 之前 輸出了 PHP 通知、警告或嚴重錯誤——或某個安全外掛封鎖了 REST 路由，又或某個轉址外掛改寫了網址——那麼回應就被污染了，編輯器也就無法剖析。

如何修復，最快的方法優先

1. 讀取主控台。 在開啟 DevTools 的狀態下重現故障。像 Uncaught TypeError ... some-plugin/build/index.js 這樣的錯誤會直接指向出問題的外掛。單單這一步就能解決大部分情況，讓你免於盲目地逐一排查。

2. 排除瀏覽器因素。 強制重新整理（Cmd/Ctrl+Shift+R），然後試著用關閉擴充功能的無痕視窗開啟。廣告封鎖器與隱私擴充功能偶爾會剝除後台指令碼。如果在無痕模式下正常運作，那問題就出在瀏覽器擴充功能或過時的快取，而不是你的網站。

3. 直接檢查 REST API，如果你看到的是「不是有效的 JSON」訊息。在瀏覽器中造訪 https://yoursite.com/wp-json/。你應該會看到一大片 JSON。如果得到的是 HTML、500 錯誤，或被導向登入頁面，那就是你的問題所在——是某個外掛破壞了 REST 回應，而不是編輯器本身。

4. 逐一排查外掛。 全部停用，確認編輯器可以載入，然後一次重新啟用一個，直到它再次壞掉。如果你完全被鎖在 wp-admin 之外，就透過 SFTP 重新命名資料夾來做：

mv wp-content/plugins wp-content/plugins_off

資料夾一消失，WordPress 就會停用一切。再把它改回原名，然後逐一把外掛移進移出。

5. 測試佈景主題。 切換到 Twenty Twenty-Four。若某個佈景主題排入了損毀的編輯器 JS，或在 functions.php 中拋出 PHP 錯誤，也會產生相同的症狀。

6. 開啟記錄並讀取真正的錯誤。 尤其針對 REST/JSON 的故障，請在 wp-config.php 中啟用除錯：

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

嚴重錯誤會連同確切的檔案與行號一起寫入 wp-content/debug.log。如果那段堆疊追蹤很密集——帶有命名空間的類別名稱、require 呼叫鏈、埋在十行追蹤底下的一個嚴重錯誤——把它貼進我們的 WordPress 錯誤記錄解碼器，就能以白話看出到底是哪個外掛、哪一行真正觸發了它。這就是「有東西壞了」與「這個特定外掛的第 214 行壞了」之間的差別。

如果你懷疑是指令碼串接掩蓋了真正的元凶，就強制每個指令碼分開載入，好讓主控台錯誤精確指向單一檔案：

define( 'SCRIPT_DEBUG', true );
define( 'CONCATENATE_SCRIPTS', false );

不該做的事

別安裝傳統編輯器（Classic Editor）外掛就當作修好了。 它什麼都沒修好——它只是把區塊編輯器藏起來，讓你不再看到錯誤。損毀的 JavaScript 或損毀的 REST 回應依然存在，之後它會在網站編輯器、在小工具，或在你下次更新時再次咬你一口。先診斷；只有在你經過深思熟慮、決定不再使用區塊時，才退回傳統編輯器。

別反射性地調高 PHP 記憶體上限。 這是網路上最愛的複製貼上式解法，但空白的編輯器極少是記憶體耗盡造成的。真正的記憶體耗盡會拋出一個明確的嚴重錯誤——「Allowed memory size of N bytes exhausted」——你會在 debug.log 中看到它。如果那一行不在，加再多記憶體也無濟於事。

別重新安裝 WordPress 核心。 核心檔案在每一個安裝上都是位元組完全相同的。如果問題出在核心，那全世界每一個 WordPress 網站現在都會有壞掉的編輯器。問題幾乎一定出在你的外掛或佈景主題上，而重新安裝核心可能會在什麼都沒修好的情況下覆蓋掉其他東西。

別把清除或停用快取外掛當作第一步盲目地做。 過度激進的 JS 最小化與串接 有可能 破壞編輯器，所以值得測試——但在你隨意到處清快取之前，先看看主控台。用猜的，正是讓一個五分鐘的修復變成一整個下午的原因。

還是卡住了？

如果主控台是乾淨的、REST API 回傳有效的 JSON，而且完整排查了外掛與佈景主題後編輯器仍舊掛掉，那答案幾乎一定就躺在 debug.log 裡。啟用 WP_DEBUG_LOG，重現故障一次，然後把產生的嚴重錯誤丟進錯誤記錄解碼器。堆疊追蹤會指出那個檔案——就從那裡開始。