Khắc phục lỗi Block Editor của WordPress không tải được

Phần lớn trường hợp, block editor của WordPress không tải được là do lỗi JavaScript — một script bị hỏng từ plugin hoặc theme làm treo toàn bộ ứng dụng React, và editor không bao giờ render xong. Hãy mở developer console của trình duyệt (F12, hoặc Cmd+Option+I trên Mac), tải lại màn hình chỉnh sửa, và đọc dòng lỗi màu đỏ. Nó gần như luôn chỉ ra file đã gây lỗi. Chỉ một dòng đó thôi đã cho bạn biết cần tắt plugin nào, và thường bạn có thể quay lại viết bài trong chưa đầy năm phút. Cài lại WordPress, tăng memory limit của PHP, và chuyển sang Classic Editor là ba gợi ý phổ biến nhất trên mạng, và cả ba thường đều là cách làm sai.

Vì sao editor lại hỏng theo kiểu như vậy

Block editor (Gutenberg) là một ứng dụng React chạy trên một trang duy nhất (single-page), nằm bên trong wp-admin/post.php và post-new.php. WordPress nạp (enqueue) một loạt các gói script — wp-blocks, wp-element, wp-editor, wp-edit-post — và ứng dụng khởi động qua wp.domReady(). JavaScript sẽ ngừng chạy ngay tại exception đầu tiên không được bắt. Vậy nên nếu bất kỳ script nào được nạp mà throw lỗi trong lúc editor đang khởi tạo, mọi thứ phía sau nó cũng chết theo. Khu vực soạn bài bạn viết cẩn thận sập thành một ô trắng trơn, hoặc hiện dòng thông báo “The editor has encountered an unexpected error.”

Mặc định WordPress còn gộp (concatenate) các script admin lại thành ít request hơn. Điều đó nghĩa là JS hỏng của một plugin có thể kéo theo cả những script không liên quan được nạp chung trong cùng bundle, và đó là lý do thủ phạm không phải lúc nào cũng lộ ra rõ ràng qua biểu hiện bên ngoài. Nhưng console thì có.

Kiểu lỗi thứ hai trông khác hẳn: editor tải được, nhưng khi lưu lại throw ra “Updating failed. The response is not a valid JSON response.” Đây không phải vấn đề JavaScript. Editor giao tiếp với REST API tại /wp-json/wp/v2/, và nó mong nhận về JSON sạch. Nếu một plugin hoặc file functions.php của theme phát ra một PHP notice, warning, hoặc fatal trước phần JSON — hoặc một plugin bảo mật chặn route REST, hoặc một plugin redirect viết lại URL — thì response bị lẫn tạp và editor không parse được.

Cách khắc phục, nhanh nhất trước

1. Đọc console. Tái hiện lại lỗi với DevTools đang mở. Một lỗi kiểu Uncaught TypeError ... some-plugin/build/index.js chỉ thẳng vào plugin gây lỗi. Chỉ riêng bước này đã xử lý được phần lớn trường hợp và giúp bạn khỏi phải mò mẫm bisect vô định.

2. Loại trừ trình duyệt. Hard-refresh (Cmd/Ctrl+Shift+R), rồi thử một cửa sổ ẩn danh (incognito) với extension đã tắt. Trình chặn quảng cáo và extension bảo mật đôi khi lược bỏ mất script admin. Nếu chạy được trong incognito thì vấn đề nằm ở một extension trình duyệt hoặc cache cũ, chứ không phải ở site của bạn.

3. Kiểm tra REST API trực tiếp nếu bạn thấy thông báo “not a valid JSON”. Truy cập https://yoursite.com/wp-json/ trên trình duyệt. Bạn sẽ thấy một loạt JSON. Nếu bạn nhận về HTML, lỗi 500, hoặc bị redirect về trang đăng nhập, thì đó chính là lỗi của bạn — một plugin đang làm hỏng response REST, chứ không phải bản thân editor.

4. Bisect các plugin. Tắt hết tất cả, xác nhận editor tải được, rồi bật lại từng cái một cho đến khi lỗi tái diễn. Nếu bạn bị khóa hoàn toàn khỏi wp-admin, hãy làm qua SFTP bằng cách đổi tên thư mục:

mv wp-content/plugins wp-content/plugins_off

WordPress sẽ tự tắt tất cả khi thư mục biến mất. Đổi tên lại như cũ, rồi di chuyển từng plugin ra vào riêng lẻ.

5. Kiểm tra theme. Chuyển sang Twenty Twenty-Four. Một theme nạp JS editor bị hỏng hoặc throw PHP trong functions.php sẽ tạo ra đúng những triệu chứng như vậy.

6. Bật log lên và đọc lỗi thật. Đặc biệt với các lỗi REST/JSON, hãy bật debug trong wp-config.php:

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

Lỗi fatal sẽ được ghi vào wp-content/debug.log cùng với đúng tên file và số dòng. Nếu stack trace đó rối rắm — tên class có namespace, chuỗi require lồng nhau, một fatal bị vùi dưới mười dòng trace — hãy dán nó vào công cụ giải mã error log của WordPress để thấy, bằng ngôn ngữ dễ hiểu, chính xác plugin nào và dòng nào đã thực sự gây ra lỗi. Đó là khác biệt giữa “có cái gì đó hỏng” và “dòng 214 của đúng plugin này bị hỏng.”

Nếu bạn nghi ngờ việc gộp script (concatenation) đang che mất thủ phạm thật, hãy ép mỗi script nạp riêng biệt để lỗi trên console chỉ vào đúng một file:

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

Những điều không nên làm

Đừng cài plugin Classic Editor rồi coi như đã fix xong. Nó không sửa được gì cả — nó chỉ giấu block editor đi để bạn không còn nhìn thấy lỗi. JavaScript hỏng hay response REST hỏng vẫn còn nguyên đó, và nó sẽ cắn bạn lần nữa ở site editor, ở widget, hoặc ở lần cập nhật tiếp theo. Hãy chẩn đoán trước; chỉ lùi về Classic nếu bạn đã cân nhắc kỹ và chủ động chọn ngừng dùng block.

Đừng theo phản xạ mà tăng memory limit của PHP. Đây là cách fix copy-paste được ưa chuộng nhất trên internet, nhưng editor trắng trơn hiếm khi là do cạn bộ nhớ. Cạn bộ nhớ thật sự sẽ throw ra một fatal cụ thể — “Allowed memory size of N bytes exhausted” — mà bạn sẽ thấy trong debug.log. Nếu dòng đó không có ở đấy thì thêm memory cũng chẳng thay đổi được gì.

Đừng cài lại WordPress core. File core giống hệt nhau đến từng byte trên mọi bản cài đặt. Nếu core là vấn đề thì mọi site WordPress trên đời này đều đang hỏng editor ngay lúc này rồi. Lỗi gần như luôn nằm ở plugin hoặc theme của bạn, và cài lại core còn có nguy cơ ghi đè lung tung mà chẳng sửa được gì.

Đừng mù quáng xóa hay tắt plugin cache ngay từ bước đầu. Việc minify và concatenate JS quá mạnh tay có thể làm hỏng editor, nên cũng đáng để thử — nhưng hãy kiểm tra console trước khi bạn đi flush cache tứ tung. Đoán mò chính là cách một fix năm phút biến thành cả buổi chiều.

Vẫn bí?

Nếu console sạch trơn, REST API trả về JSON hợp lệ, và bisect hết cả plugin lẫn theme mà editor vẫn chết, thì câu trả lời gần như luôn nằm sẵn trong debug.log. Hãy bật WP_DEBUG_LOG, tái hiện lỗi một lần, và đưa fatal thu được chạy qua công cụ giải mã error log. Stack trace sẽ chỉ ra tên file — hãy bắt đầu từ đó.