WP_DEBUG: دیباگ حرفه‌ای وردپرس

وقتی سایت وردپرسی شما صفحهٔ سفید نشان می‌دهد یا افزونه‌ای رفتار عجیبی دارد، اولین ابزارتان WP_DEBUG است. ولی روشن کردن سادهٔ آن روی سایت زنده، اشتباهی است که می‌تواند اطلاعات مسیر سرور و ساختار دیتابیس را جلوی چشم بازدیدکنندگان بگذارد.

این مقاله روش درست است.

تنظیم امن

در فایل wp-config.php، پیش از خط /* That's all, stop editing! */:

define('WP_DEBUG', true);          // دیباگ روشن
define('WP_DEBUG_LOG', true);      // در فایل بنویس
define('WP_DEBUG_DISPLAY', false); // ولی روی صفحه نشان نده
@ini_set('display_errors', 0);

ترکیب این چهار خط نکتهٔ اصلی است: خطاها ثبت می‌شوند ولی بازدیدکننده چیزی نمی‌بیند. خطاها در wp-content/debug.log می‌نشینند.

اگر فقط WP_DEBUG را روشن کنید و بقیه را ننویسید، پیام‌های خطا مستقیم در صفحه چاپ می‌شوند — که هم زشت است و هم اطلاعات ساختار سرور را لو می‌دهد.

لاگ را جای بهتری بگذارید

مسیر پیش‌فرض wp-content/debug.log از طریق مرورگر قابل دسترسی است. اگر می‌توانید، به مسیری بیرون از دسترس عمومی منتقلش کنید:

define('WP_DEBUG_LOG', '/home/user/logs/wp-debug.log');

اگر نمی‌توانید، دست‌کم یک فایل .htaccess در همان پوشه بگذارید که دسترسی به فایل‌های .log را ببندد.

تنظیمات مفید دیگر

define('SCRIPT_DEBUG', true);   // نسخهٔ غیرفشردهٔ فایل‌های خود وردپرس
define('SAVEQUERIES', true);    // ثبت همهٔ کوئری‌های دیتابیس

SAVEQUERIES برای پیدا کردن کندی مفید است، ولی خودش سربار دارد و هرگز نباید روی سایت زنده روشن بماند.

لاگ را چطور بخوانیم

فایل debug.log سه نوع پیام دارد و تفکیکشان مهم است:

Fatal error — اجرا متوقف شده. این‌ها علت صفحهٔ سفیدند و اولویت اولند.

Warning — چیزی درست نبود ولی ادامه پیدا کرد. اغلب نشانهٔ باگی است که هنوز خودش را نشان نداده.

Notice و Deprecated — معمولاً پرحجم‌ترین و کم‌اهمیت‌ترین. Deprecated یعنی کدی از قابلیتی استفاده می‌کند که در نسخه‌های آینده حذف می‌شود — مهم برای نگهداری بلندمدت، نه برای بحران امروز.

توصیهٔ عملی: پیش از تحقیق، فایل را خالی کنید، بعد مشکل را بازتولید کنید. آن‌وقت هرچه در فایل هست مربوط به همان لحظه است، نه به هفتهٔ گذشته.

پیدا کردن افزونهٔ مقصر

وقتی می‌دانید مشکلی هست ولی نمی‌دانید از کجاست، روش نصف کردن سریع‌ترین راه است:

• همهٔ افزونه‌ها را غیرفعال کنید. مشکل رفت؟ پس از افزونه‌هاست.
• نصف آن‌ها را روشن کنید. مشکل برگشت؟ در همین نصف است. نه؟ در نصف دیگر.
• تکرار کنید.

با ۳۲ افزونه، پنج بار تست کافی است. اگر با غیرفعال کردن همه هم مشکل باقی ماند، قالب را به یکی از قالب‌های پیش‌فرض وردپرس عوض کنید — اگر رفت، مشکل از قالب است.

روی سایت زنده این کار را نکنید. اگر محیط آزمایشی ندارید، دست‌کم در ساعت کم‌ترافیک انجامش دهید.

صفحهٔ سفید مرگ

وردپرس امروز معمولاً به‌جای صفحهٔ سفید، پیام «مشکل فنی» نشان می‌دهد و به ایمیل مدیر خبر می‌دهد. اگر همچنان صفحهٔ سفید می‌بینید:

• WP_DEBUG_LOG را روشن کنید و debug.log را ببینید.
• اگر لاگ خالی است، مشکل احتمالاً پیش از بارگذاری وردپرس رخ می‌دهد — لاگ خطای خود PHP در cPanel را ببینید.
• حافظه را بررسی کنید: define('WP_MEMORY_LIMIT', '256M');

Query Monitor: چیزی که WP_DEBUG نمی‌دهد

اگر یک ابزار به مجموعه‌تان اضافه می‌کنید، این باشد. افزونهٔ Query Monitor نواری در پیشخوان اضافه می‌کند که برای هر صفحه نشان می‌دهد:

• همهٔ کوئری‌های دیتابیس، با زمان اجرا و اینکه کدام افزونه هرکدام را زده.
• قلاب‌ها و اکشن‌هایی که اجرا شده‌اند.
• درخواست‌های HTTP خارجی — منبع رایج کندی، چون افزونه‌ای که به سرور کندی وصل می‌شود، کل صفحه را معطل می‌کند.
• خطاها و هشدارهای PHP همان صفحه، بدون نیاز به خواندن فایل لاگ.

ستون «کدام افزونه» ارزشمندترین بخش است: وقتی صفحه‌ای کند است، معمولاً در چند ثانیه معلوم می‌شود مقصر کیست — کاری که با روش نصف کردن ممکن است یک ساعت طول بکشد.

فقط یادتان باشد که این هم ابزار تشخیص است، نه ابزار همیشگی؛ روی سایت زنده فعالش نگذارید.

Site Health و لاگ سرور

دو منبع اطلاعاتی دیگر که اغلب نادیده گرفته می‌شوند.

ابزارها ← سلامت سایت در خود وردپرس، نسخهٔ PHP، افزونه‌های قدیمی، و مشکلات پیکربندی را فهرست می‌کند. تب «اطلاعات» همان چیزی است که باید موقع درخواست کمک، کپی و ارسال کنید.

لاگ خطای PHP در cPanel جای دیگری است که باید نگاه کنید. اگر debug.log خالی است ولی سایت خطا می‌دهد، مشکل احتمالاً پیش از بارگذاری وردپرس رخ می‌دهد — خطای نحوی در فایلی، کمبود حافظه، یا مشکل دسترسی — و فقط در لاگ سطح سرور دیده می‌شود.

محدودیت مهم: اینجا فقط PHP است

و حالا نکته‌ای که بسیاری از صاحبان سایت وردپرسی دیر متوجهش می‌شوند.

WP_DEBUG فقط خطاهای سمت سرور را می‌بیند. خطاهای جاوااسکریپت — که در مرورگر کاربر رخ می‌دهند — هرگز در debug.log نمی‌آیند.

و در وردپرس امروزی، بخش بزرگی از تجربهٔ کاربر به جاوااسکریپت وابسته است: فرم تماس، سبد خرید ووکامرس، اسلایدر، فیلتر محصولات، درگاه پرداخت. اگر افزونه‌ای با افزونهٔ دیگری تداخل جاوااسکریپتی داشته باشد:

• لاگ سرور تمیز است.
• سایت از دید شما سالم است.
• ولی دکمهٔ «افزودن به سبد» برای بخشی از کاربران کار نمی‌کند.

این حالت در سایت‌های وردپرسی با چند افزونه، بسیار رایج است — و دقیقاً همان دسته‌ای است که ماه‌ها بدون کشف باقی می‌ماند.

پوشش دادن نیمهٔ دوم

برای دیدن خطاهای سمت مرورگر، به چیزی نیاز دارید که در مرورگر کاربر اجرا شود و خطاها را به شما برساند. سبک‌ترین راهش افزودن یک تگ اسکریپت است — که در وردپرس با چند خط در functions.php قالب فرزند انجام می‌شود، بدون نصب افزونهٔ سنگین. روش سبکش را در رصد خطای جاوااسکریپت در وردپرس بدون افزونهٔ سنگین قدم‌به‌قدم آورده‌ایم.

ترکیب این دو، تصویر کامل می‌دهد: WP_DEBUG برای PHP، و ثبت خطای مرورگر برای جاوااسکریپت. هیچ‌کدام جای دیگری را نمی‌گیرد.

و در آخر: خاموشش کنید

وقتی کارتان تمام شد، WP_DEBUG را روی false بگذارید و فایل debug.log را حذف کنید. لاگی که ماه‌ها روشن مانده، هم حجم می‌گیرد و هم اطلاعاتی دارد که نباید در دسترس بماند.

منابع و مطالعهٔ بیشتر

• Debugging in WordPress — مستندات رسمی WP_DEBUG و ثابت‌های مرتبط
• ویرایش wp-config.php — مرجع رسمی تنظیمات
• افزونهٔ Query Monitor — کوئری‌ها، قلاب‌ها و خطاهای PHP هر صفحه
• صفحهٔ Site Health — ابزار عیب‌یابی داخلی وردپرس