WordPress Debug là gì? Hướng dẫn chi tiết

Website WordPress của bạn đột nhiên hiện “màn hình trắng chết chóc” (White Screen of Death), báo lỗi 500, hoặc một plugin nào đó khiến trang chủ trống trơn? Trước khi hoảng loạn gọi thợ, bạn hoàn toàn có thể tự mình tìm ra nguyên nhân nhờ một công cụ có sẵn ngay trong lõi WordPress: chế độ Debug. Bài viết này sẽ hướng dẫn bạn từ A đến Z cách bật, đọc, hiểu và tắt debug một cách an toàn — kể cả trên website đang chạy thật.

WordPress Debug là gì và tại sao quan trọng?

Debug (gỡ lỗi) là quá trình tìm và sửa các lỗi trong phần mềm. Trong WordPress, “chế độ debug” là một cơ chế tích hợp sẵn giúp hiển thị hoặc ghi lại tất cả các lỗi, cảnh báo và thông báo mà PHP gặp phải khi chạy website của bạn. Mặc định, WordPress che giấu hầu hết các lỗi này để website trông gọn gàng với khách truy cập — nhưng điều đó cũng đồng nghĩa bạn không biết chuyện gì đang xảy ra phía sau khi có sự cố.

Khi bật debug, thay vì chỉ thấy một trang trắng vô nghĩa, bạn sẽ nhận được thông tin cụ thể như: lỗi nằm ở file nào, dòng số mấy, do plugin hay theme nào gây ra. Đây chính là “kim chỉ nam” để xử lý sự cố thay vì mò mẫm vô định.

Những tình huống điển hình mà debug cứu bạn:

• Website hiện trang trắng sau khi cài hoặc cập nhật plugin.
• Lỗi “There has been a critical error on this website”.
• Trang tải rất chậm và bạn nghi ngờ có truy vấn database “rác”.
• Nhà phát triển plugin/theme yêu cầu bạn gửi file debug.log để hỗ trợ.

Các hằng số debug trong wp-config.php

Toàn bộ chế độ debug được điều khiển bằng vài hằng số (constants) PHP khai báo trong file wp-config.php — file cấu hình nằm ở thư mục gốc của WordPress. Dưới đây là bảng tổng hợp những hằng số quan trọng nhất:

Hằng số	Chức năng
WP_DEBUG	Công tắc tổng. Bật/tắt toàn bộ chế độ debug. Mặc định là false.
WP_DEBUG_LOG	Ghi tất cả lỗi vào file wp-content/debug.log thay vì hiển thị ra màn hình.
WP_DEBUG_DISPLAY	Quyết định lỗi có hiển thị trực tiếp trên trang web hay không. Nên đặt false trên web thật.
SCRIPT_DEBUG	Buộc WordPress dùng phiên bản đầy đủ (chưa nén) của file CSS/JS lõi — hữu ích khi debug giao diện.
SAVEQUERIES	Lưu lại mọi truy vấn database để phân tích hiệu năng. Tốn bộ nhớ, chỉ bật khi cần.

WP_DEBUG — công tắc chính

Đây là hằng số quan trọng nhất. Khi WP_DEBUG bằng true, WordPress sẽ kích hoạt báo cáo lỗi đầy đủ. Cách bật cơ bản nhất:

define( 'WP_DEBUG', true );

Tuy nhiên, nếu chỉ bật mỗi dòng này trên website thật, lỗi sẽ hiển thị thẳng ra trang cho mọi khách truy cập nhìn thấy — điều này vừa xấu, vừa nguy hiểm về bảo mật. Vì vậy ta cần kết hợp với các hằng số khác.

WP_DEBUG_LOG và WP_DEBUG_DISPLAY

Hai hằng số này thường đi cùng nhau. WP_DEBUG_LOG chuyển hướng lỗi vào một file văn bản thầm lặng, còn WP_DEBUG_DISPLAY kiểm soát việc lỗi có hiện ra cho người dùng hay không.

SCRIPT_DEBUG và SAVEQUERIES

SCRIPT_DEBUG dành cho lập trình viên giao diện: khi bật, WordPress sẽ nạp file .js và .css bản gốc thay vì bản .min đã nén, giúp dễ đọc khi gỡ lỗi front-end. Còn SAVEQUERIES lưu mọi câu lệnh SQL vào biến toàn cục $wpdb->queries để bạn xem plugin nào đang “ngốn” database. Vì nó lưu rất nhiều dữ liệu nên hãy tắt ngay khi không dùng để tránh tốn RAM.

Cách bật debug an toàn trên website thật

Trên môi trường thật (production), nguyên tắc vàng là: ghi lỗi vào file, không hiển thị ra màn hình. Khách truy cập sẽ không thấy gì bất thường, nhưng bạn vẫn có đầy đủ thông tin trong log. Hãy làm theo các bước sau.

Đoạn cấu hình debug an toàn dành cho website thật như sau:

// Bật chế độ debug
define( 'WP_DEBUG', true );

// Ghi lỗi vào wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// KHÔNG hiển thị lỗi ra màn hình cho khách
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Nếu bạn đang phát triển trên máy cá nhân (localhost) và muốn xem lỗi ngay lập tức, bạn có thể đặt WP_DEBUG_DISPLAY thành true — nhưng tuyệt đối không làm vậy trên web thật.

Cách đọc và hiểu file debug.log

Sau khi bật WP_DEBUG_LOG và lỗi đã xảy ra, WordPress sẽ tạo file log tại đường dẫn:

wp-content/debug.log

Mở file này bằng File Manager hoặc FTP. Mỗi dòng trong log đại diện cho một sự kiện lỗi, có cấu trúc gồm: dấu thời gian, loại lỗi, nội dung mô tả, và quan trọng nhất là đường dẫn file cùng số dòng nơi lỗi xảy ra. Ví dụ một dòng log điển hình:

[29-May-2026 08:14:22 UTC] PHP Warning:  Undefined array key "user_id"
in /wp-content/plugins/contact-form/form.php on line 88

Cách “giải mã” dòng trên:

• Thời gian: lỗi xảy ra lúc 08:14 ngày 29/05.
• Loại: PHP Warning — cảnh báo, không nghiêm trọng.
• Thủ phạm: plugin contact-form, file form.php, dòng 88.

Các lỗi thường gặp và ý nghĩa của chúng

Không phải dòng log nào cũng đáng lo. Hiểu được mức độ nghiêm trọng của từng loại sẽ giúp bạn ưu tiên đúng việc. Dưới đây là những loại lỗi phổ biến nhất.

PHP Notice và PHP Warning

Đây là những thông báo “nhẹ”. Notice thường chỉ là gợi ý code chưa tối ưu (ví dụ dùng biến chưa khai báo). Warning nghiêm trọng hơn một chút nhưng website vẫn chạy được. Bạn không cần sửa ngay, nhưng nếu log đầy ắp Warning, đó là dấu hiệu plugin/theme đang viết cẩu thả và nên cân nhắc thay thế.

PHP Fatal error

Đây mới là thủ phạm khiến website “sập” hoặc hiện trang trắng. “Fatal” nghĩa là PHP không thể tiếp tục chạy. Ví dụ thường gặp:

PHP Fatal error:  Uncaught Error: Call to undefined function
wc_get_product() in /wp-content/themes/shop/functions.php:45

Dòng này cho biết theme đang gọi một hàm của WooCommerce nhưng plugin WooCommerce chưa được kích hoạt. Cách xử lý là kích hoạt lại plugin liên quan, hoặc sửa code để kiểm tra hàm tồn tại trước khi gọi.

“Headers already sent”

Lỗi Cannot modify header information - headers already sent xảy ra khi có nội dung (thường là một dấu cách thừa hoặc dòng trống) được in ra trước khi WordPress kịp gửi header HTTP. Log sẽ chỉ rõ file và dòng gây ra — thường là khoảng trắng dư thừa ở đầu hoặc cuối file functions.php hay wp-config.php, đặc biệt là sau thẻ đóng ?>.

Allowed memory size exhausted

Thông báo Allowed memory size of 134217728 bytes exhausted nghĩa là PHP đã cạn bộ nhớ cho phép. Cách khắc phục nhanh là tăng giới hạn bộ nhớ trong wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );

Deprecated function

Thông báo Deprecated báo rằng một hàm đang dùng đã lỗi thời và sẽ bị gỡ bỏ ở phiên bản WordPress/PHP tương lai. Website vẫn chạy bình thường hôm nay, nhưng đây là lời nhắc cập nhật plugin/theme trước khi nó “vỡ” sau này.

Query Monitor — công cụ debug trực quan

Nếu bạn thấy việc lục lọi file log quá khô khan, có một lựa chọn thân thiện hơn nhiều: plugin miễn phí Query Monitor. Đây là công cụ debug hàng đầu trong cộng đồng WordPress, hiển thị toàn bộ thông tin gỡ lỗi ngay trên thanh admin một cách trực quan.

Sau khi cài và kích hoạt, Query Monitor cho bạn xem ngay trong trình duyệt:

• Mọi truy vấn database, sắp xếp theo plugin nào tốn thời gian nhất.
• Tất cả PHP errors, warnings và notices trên từng trang cụ thể.
• Các hook, template đang được dùng và lệnh gọi HTTP từ bên ngoài.
• Thời gian tải trang và lượng bộ nhớ PHP đã dùng.

Cách tìm xung đột plugin và giao diện

Phần lớn sự cố WordPress đến từ xung đột giữa các plugin với nhau, hoặc giữa plugin và theme. Khi log chỉ ra một plugin cụ thể, việc xử lý khá dễ. Nhưng khi không rõ thủ phạm, hãy dùng phương pháp loại trừ kinh điển sau.

Tắt debug khi đã xong và lưu ý bảo mật

Đây là bước cực kỳ quan trọng mà nhiều người quên: luôn tắt debug sau khi đã sửa xong lỗi. Để debug bật liên tục trên web thật vừa làm chậm website (do liên tục ghi log), vừa tạo rủi ro bảo mật.

Để tắt, hãy quay lại wp-config.php và đổi giá trị về false:

define( 'WP_DEBUG', false );

Hoặc xóa hẳn các dòng debug bạn đã thêm. Đừng quên hai việc dọn dẹp quan trọng sau:

• Xóa file wp-content/debug.log — file này có thể chứa đường dẫn server, tên file nhạy cảm.
• Gỡ plugin Query Monitor nếu bạn chỉ cài để debug tạm thời.

Để chặn truy cập file log qua trình duyệt, bạn có thể thêm đoạn sau vào file .htaccess ở thư mục gốc:

<Files debug.log>
    Order allow,deny
    Deny from all
</Files>

Câu hỏi thường gặp