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

WP_DEBUG: دیباگ حرفه‌ای وردپرس
در این مقاله می‌خوانید
  1. تنظیم امن
  2. لاگ را جای بهتری بگذارید
  3. تنظیمات مفید دیگر
  4. لاگ را چطور بخوانیم
  5. پیام‌های رایج در debug.log
  6. لاگ خودتان را بنویسید
  7. پیدا کردن افزونهٔ مقصر
  8. صفحهٔ سفید مرگ
  9. ایمیل حالت بازیابی را جدی بگیرید
  10. Query Monitor: چیزی که WP_DEBUG نمی‌دهد
  11. Site Health و لاگ سرور
  12. تنظیم جدا برای سایت آزمایشی
  13. محدودیت مهم: اینجا فقط PHP است
  14. پوشش دادن نیمهٔ دوم
  15. و در آخر: خاموشش کنید
  16. منابع و مطالعهٔ بیشتر

وقتی سایت وردپرسی شما صفحهٔ سفید نشان می‌دهد یا افزونه‌ای رفتار عجیبی دارد، اولین ابزارتان 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 یعنی کدی از قابلیتی استفاده می‌کند که در نسخه‌های آینده حذف می‌شود — مهم برای نگهداری بلندمدت، نه برای بحران امروز.

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

پیام‌های رایج در debug.log

چند پیام را بارها خواهید دید و دانستن معنایشان، نیمی از تشخیص است:

Allowed memory size of ... bytes exhausted — Fatal. حافظهٔ PHP تمام شده. بالا بردن WP_MEMORY_LIMIT علامت را برطرف می‌کند، ولی اگر بعد از افزایش هم تکرار شد، احتمالاً حلقه‌ای بی‌پایان یا کوئری‌ای در کار است که همه‌چیز را یکجا بار می‌کند. فایلی که در همان خط آمده لزوماً مقصر نیست؛ فقط جایی است که حافظه تمام شد.

Uncaught TypeError — Fatal، و در PHP 8 رایج‌تر از قبل. جایی که PHP 7 هشدار می‌داد و ادامه می‌داد، PHP 8 اجرا را متوقف می‌کند؛ نمونهٔ آشنا count() روی مقداری است که آرایه نیست. اگر درست بعد از ارتقای PHP صفحه سفید شد، اول دنبال همین بگردید.

Warning: Undefined array key و Warning: Undefined variable — این‌ها در PHP 8 از Notice به Warning ارتقا پیدا کرده‌اند؛ برای همین بعد از ارتقای PHP ناگهان لاگ پر از آن‌ها می‌شود. سایت را از کار نمی‌اندازند، ولی معمولاً نشانهٔ کدی‌اند که حالتی را پیش‌بینی نکرده.

Function _load_textdomain_just_in_time was called incorrectly — از وردپرس ۶.۷. افزونه یا قالبی پیش از قلاب init ترجمه‌هایش را بارگذاری کرده. فقط وقتی WP_DEBUG روشن است دیده می‌شود و رفعش با سازندهٔ همان افزونه است؛ نام دامنهٔ ترجمه در متن پیام می‌گوید کدام.

Cannot modify header information - headers already sent by (output started at ...) — Warning. بخش مهمش داخل پرانتز است: فایل و شماره‌خطی که خروجی را زودتر از موعد شروع کرده. اغلب فاصله یا خط خالی بعد از ?> در انتهای یک فایل PHP است، یا پیام خطای دیگری که روی صفحه چاپ شده.

لاگ خودتان را بنویسید

همهٔ باگ‌ها خطا نمی‌سازند. وقتی سفارشی وضعیت اشتباه می‌گیرد یا ایمیلی ارسال نمی‌شود، چیزی در debug.log نمی‌آید، چون از دید PHP همه‌چیز درست بوده. اینجا خودتان پیام بنویسید. وقتی WP_DEBUG_LOG روشن است، تابع error_log در همان فایل می‌نویسد:

error_log('order ' . $order_id . ' status: ' . $status);
error_log(print_r($data, true));            // آرایه یا شیء
error_log(wp_debug_backtrace_summary());    // چه کدی این تابع را صدا زده

خط سوم در وردپرس به‌ویژه مفید است، چون کد شما معمولاً از داخل یک قلاب اجرا می‌شود؛ این تابع زنجیرهٔ فراخوانی را همراه با نام قلاب‌ها در یک خط برمی‌گرداند.

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

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

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

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

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

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

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

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

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

ایمیل حالت بازیابی را جدی بگیرید

ایمیلی که وردپرس هنگام خطای Fatal به مدیر می‌فرستد، از نسخهٔ ۵.۲ به بعد بخشی از سازوکاری به نام حالت بازیابی (Recovery Mode) است و دو چیز ارزشمند دارد:

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

دو چیز معمولاً این سازوکار را بی‌اثر می‌کند:

  • ایمیل به نشانی «ایمیل مدیریت» در تنظیمات عمومی می‌رود، که ممکن است صندوقی باشد که کسی نمی‌خواند. با ثابت RECOVERY_MODE_EMAIL می‌توانید نشانی دیگری بدهید.
  • اگر سرور ایمیل نمی‌فرستد یا ایمیل‌هایش به اسپم می‌رود، این هشدار هرگز نمی‌رسد. یک بار مطمئن شوید ایمیل‌های وردپرس واقعاً به مقصد می‌رسند.
define('RECOVERY_MODE_EMAIL', 'dev@example.com');

عکسش هم ممکن است: روی محیط توسعه، اگر می‌خواهید خطای Fatal را خام و بی‌واسطه ببینید، define('WP_DISABLE_FATAL_ERROR_HANDLER', true); این سازوکار را خاموش می‌کند. روی سایت زنده این کار را نکنید.

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

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

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

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

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

Site Health و لاگ سرور

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

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

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

تنظیم جدا برای سایت آزمایشی

اگر نسخهٔ آزمایشی (staging) دارید، دیباگ را به نوع محیط گره بزنید. وردپرس از نسخهٔ ۵.۵ ثابت WP_ENVIRONMENT_TYPE را می‌شناسد، با مقدارهای local، development، staging و production؛ پیش‌فرض production است.

define('WP_ENVIRONMENT_TYPE', 'staging');   // روی سایت زنده: 'production'

if (WP_ENVIRONMENT_TYPE === 'production') {
    define('WP_DEBUG', false);
} else {
    define('WP_DEBUG', true);
    define('WP_DEBUG_LOG', true);
    define('WP_DEBUG_DISPLAY', false);
}

خط اول باید در wp-config.php هر دو نسخه باشد، هرکدام با مقدار خودش. اگر روی یکی جا بیفتد، شرط بعدی به ثابتی تعریف‌نشده می‌رسد و در PHP 8 این خودش خطای Fatal است.

فایدهٔ دوم: کد شما می‌تواند با wp_get_environment_type() بفهمد کجا اجرا می‌شود — مثلاً روی نسخهٔ آزمایشی پیامک واقعی نفرستد. هنگام انتقال سایت به زنده هم حواستان باشد که wp-config.php نسخهٔ آزمایشی همراهش نرود؛ این از همان تفاوت‌های کوچکی است که باگ‌هایی فقط در production می‌سازد.

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

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

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

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

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

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

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

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

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

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

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

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

باگ‌ماگ را رایگان امتحان کنید

خطاهای سایتتان را خودکار ثبت کنید و بگذارید کاربران با یک کلیک باگ گزارش دهند.

شروع رایگان