وقتی WP_DEBUG_LOG با مقدار استاندارد فعال باشد، فایل معمولاً در wp-content/debug.log ساخته می‌شود. نبودن فایل به معنی نبودن خطا نیست: مسیر content می‌تواند سفارشی باشد، PHP اجازه نوشتن نداشته باشد یا خطا پیش از bootstrap وردپرس رخ دهد. هدف فقط پیدا کردن فایل نیست؛ باید یک پیام مشخص را به همان درخواست خراب وصل کنید.
پاسخ سریع: خطا را یک بار با زمان دقیق بازتولید کنید، timezone لاگ را بشناسید، خطوط اطراف همان زمان را بخوانید و نخستین Fatal یا Exception مرتبط با کد پروژه را دنبال کنید. آخرین خط stack trace یا یک Warning قدیمی الزاماً علت اصلی نیست.
مسیر فایل چگونه تعیین می‌شود؟
با مقدار true مقصد معمول داخل پوشه content است. اگر WP_CONTENT_DIR تغییر کرده یا برای WP_DEBUG_LOG مسیر دیگری تعیین شده باشد، فایل جای دیگری قرار می‌گیرد. مقصد باید برای کاربر PHP قابل نوشتن و از دانلود عمومی محافظت شود. فایل wp-config حاوی secret است؛ آن را برای درخواست کمک ارسال نکنید.
اگر debug.log ساخته نمی‌شود
- مطمئن شوید ثابت‌ها قبل از خط توقف wp-config و فقط یک بار تعریف شده‌اند.
- درخواست خراب را دوباره اجرا و timestamp را ثبت کنید.
- مالکیت و permission مسیر را با کاربر PHP تطبیق دهید؛ از
777استفاده نکنید. - لاگ PHP-FPM، Apache یا پنل هاست را ببینید.
- در Docker، volume، stdout و node اجراکننده درخواست را بررسی کنید.
Fatal مربوط به syntax در wp-config یا extension گمشده ممکن است قبل از logger وردپرس رخ دهد و فقط در error log سطح PHP دیده شود.
از زمان شروع کنید، نه نام افزونه
ساعت کلیک یا job را با ثانیه یادداشت و اختلاف timezone سیستم‌عامل، PHP و وردپرس را مشخص کنید. سپس بازه کوچکی را جدا کنید. جست‌وجوی نام افزونه ممکن است صدها Warning بی‌ربط روزهای قبل را برگرداند. در چند backend، request ID بهترین راه اتصال لاگ proxy، PHP و برنامه است.
tail -n 200 wp-content/debug.log
grep -nE "PHP Fatal|Uncaught" wp-content/debug.logاین دستورها فقط فایل را می‌خوانند، اما خروجی ممکن است داده حساس داشته باشد. مسیر را با نصب واقعی تطبیق دهید و کل فایل را در فضای عمومی paste نکنید.
Severity را درست تفسیر کنید
| نوع | معنا | اقدام |
|---|---|---|
| Fatal / Uncaught | درخواست معمولاً متوقف شده | پیام و نخستین frame مرتبط را دنبال کنید |
| Warning | اجرای قابل ادامه یا داده نامعتبر | ارتباط زمانی و اثر را بسنجید |
| Deprecated | API قدیمی | برای سازگاری آینده اصلاح شود؛ لزوماً علت قطعی نیست |
| Database error | query، اتصال یا schema | لاگ MySQL و عملیات همان درخواست را مقایسه کنید |
Stack trace را چگونه بخوانیم؟
از پیام exception و فایل شروع کنید، سپس frameها را تا نخستین کد متعلق به افزونه، قالب یا پروژه دنبال کنید. frame آخر معمولاً dispatcher عمومی است. اگر دو مؤلفه در trace هستند، ترکیب نسخه‌ها را در staging بازتولید کنید؛ نام آخرین فایل دلیل کافی برای حذف افزونه نیست.
چرا فایل ناگهان بزرگ می‌شود؟
Warning داخل loop، bot traffic یا روشن ماندن debug می‌تواند I/O بالا و دیسک پر ایجاد کند. نمونه لازم را حفظ، منبع تکرار را اصلاح و rotation و retention تعریف کنید. حذف فایل بدون رفع علت تنها چند دقیقه زمان می‌خرد.
پیش از اشتراک‌گذاری چه چیزهایی حذف شوند؟
- cookie، nonce، token و header احراز هویت
- رمز و DSN دیتابیس
- ایمیل، تلفن، IP و داده سفارش
- کلید API و payload کامل webhook
- مسیرهای شامل نام کاربری سیستم
از یافته تا اصلاح قابل اثبات
یک فرضیه از پیام و trace بنویسید، فقط یک متغیر را در staging تغییر دهید و سناریوی اصلی را دوباره اجرا کنید. نبود Fatal تازه و سالم بودن مسیرهای مجاور باید کنترل شود. برای فعال‌سازی امن logging، راهنمای Debug وردپرس را ببینید.
لاگ وردپرس را با لاگ سرور تطبیق دهید
یک پاسخ 500 ممکن است در debug.log پیام برنامه، در PHP-FPM علت termination و در Nginx فقط upstream failure ثبت کند. هیچ‌کدام به‌تنهایی تصویر کامل نیستند. status، مدت درخواست، PID یا request ID و timestamp را کنار هم بگذارید. اگر سیستم OOM Killer فرایند را بسته یا timeout خارج از PHP رخ داده باشد، debug.log احتمالاً آخرین علت را نشان نمی‌دهد.
بعد از اصلاح چه چیزهایی را تست کنیم؟
URL اصلی، مسیر ورود، REST API، cron و عملیاتی را که افزونه خراب انجام می‌داد دوباره اجرا کنید. نبود پیام قبلی کافی نیست؛ پاسخ باید از نظر داده و اثر جانبی نیز درست باشد. چند دقیقه لاگ تازه را مانیتور و workaroundهای موقت، debug اضافی و دسترسی‌های بازشده را جمع کنید.
چه زمانی بررسی تخصصی لازم است؟
اگر خطا متناوب، چندسروری یا وابسته به بار است، داده چند لایه باید correlate شود. سرویس رفع مشکل فنی وردپرس برای تحلیل هماهنگ WordPress، PHP و وب‌سرور قابل استفاده است.
پرسش‌های متداول
آیا می‌توان debug.log را پاک کرد؟
پس از نگه داشتن نمونه لازم و رفع منبع، rotation یا truncate کنترل‌شده ممکن است؛ اول فضای دیسک و backup را در نظر بگیرید.
چرا ساعت لاگ متفاوت است؟
timezone لایه‌ها متفاوت است. اختلاف را اندازه بگیرید و همه timestampها را به یک مبنا تبدیل کنید.
آیا هر Deprecated نیازمند rollback است؟
خیر؛ باید برنامه اصلاح داشته باشد، اما ارتباطش با خرابی فعلی باید اثبات شود.