محل لاگ دیباگ وردپرس: فایل debug.log کجاست و چطور جابه‌جایش کنیم

وردپرس لاگ دیباگ خود را به‌طور پیش‌فرض در wp-content/debug.log می‌نویسد — روی دیسک با مسیر مطلقی مثل /path/to/your/site/wp-content/debug.log. این فایل تا وقتی چیزی واقعاً ثبت نشود وجود ندارد، و اصلاً زمانی نوشته می‌شود که WP_DEBUG برابر true باشد و WP_DEBUG_LOG در wp-config.php فعال شده باشد. همین محل پیش‌فرض یک مشکل امنیتی واقعی هم هست، چون روی بیشتر هاست‌ها هر کسی می‌تواند آن را در مرورگر بگیرد.

سه ثابت و کاری که هرکدام می‌کنند

هر سه در wp-config.php می‌روند، بالای خطی که نوشته /* That's all, stop editing! Happy blogging. */. هرچه زیر آن خط اضافه شود بعد از بالا آمدن وردپرس اجرا می‌شود و نادیده گرفته می‌شود.

ثابت	پیش‌فرض	چه کار می‌کند
WP_DEBUG	false	کلید اصلی. سطح گزارش خطای PHP را بالا می‌برد تا نوتیس‌ها، هشدارها و موارد منسوخ‌شده را نشان دهد. هیچ‌کدام از موارد این فهرست بدون آن کار نمی‌کنند.
WP_DEBUG_LOG	false	خطاها را به یک فایل می‌فرستد. مقدار true یعنی wp-content/debug.log. یک رشته به‌عنوان مسیر فایل مقصد در نظر گرفته می‌شود.
WP_DEBUG_DISPLAY	true	خطاها را داخل HTML صفحه چاپ می‌کند، قابل دیدن برای هر بازدیدکننده.

وابستگی میان این‌ها همان چیزی است که مردم اشتباه می‌گیرند. مقدار WP_DEBUG_LOG داخل شاخه WP_DEBUG در کد راه‌اندازی وردپرس خوانده می‌شود. اگر WP_DEBUG برابر false باشد، true کردن WP_DEBUG_LOG هیچ کاری نمی‌کند — نه فایلی، نه خطایی، نه هشداری. اگر WP_DEBUG_LOG را اضافه کرده‌اید و هیچ لاگی ظاهر نشده، اول WP_DEBUG را بررسی کنید.

یک پیکربندی کارآمد برای سایت زنده:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

اگر WP_DEBUG بالاتر در همان فایل از قبل تعریف شده — که معمولاً هست، با مقدار false — همان خط موجود را ویرایش کنید به‌جای اینکه یک define() دوم اضافه کنید. تعریف دوباره یک ثابت باعث هشدار PHP می‌شود که روی سایتی با نمایش خطای روشن، درست بالای صفحه شما می‌نشیند.

چرا WP_DEBUG_DISPLAY باید در محیط عملیاتی false باشد

با روشن بودن نمایش، خطاهای PHP داخل پاسخ HTML چاپ می‌شوند. تنها یک نوتیس منسوخ‌شدن از یک قالب، مسیر مطلق فایل‌سیستم سرور شما را برای هر بازدیدکننده چاپ می‌کند. یک خطای پایگاه داده نام جدول‌ها و تکه‌های کوئری را چاپ می‌کند. بدتر اینکه خروجی‌ای که پیش از ارسال هدرها ظاهر می‌شود، ریدایرکت‌ها را می‌شکند، پاسخ‌های REST و AJAX را که انتظار JSON تمیز دارند خراب می‌کند و می‌تواند همان صفحه سفیدی را بسازد که مردم بعداً تقصیر یک افزونه می‌اندازند.

یک ظرافت که دانستنش می‌ارزد: تنظیم WP_DEBUG_DISPLAY روی null با false یکی نیست. مقدار null به وردپرس می‌گوید تنظیم display_errors خود PHP را دست نزند و هرچه سرور پیکربندی کرده به ارث ببرد. مقدار false فعالانه آن را خاموش می‌کند. روی سایت عملیاتی از false استفاده کنید و خط ini_set بالا را هم به‌عنوان لایه احتیاط اضافه کنید، چون یک افزونه می‌تواند بعداً در همان درخواست display_errors را دوباره روشن کند.

محل پیش‌فرض به‌صورت عمومی قابل دریافت است

فایل wp-content/debug.log داخل ریشه وب قرار دارد. هیچ چیزی در یک نصب استاندارد وردپرس جلوی درخواست‌های مستقیم به آن را نمی‌گیرد. روی یک پیکربندی معمول Apache یا nginx، نشانی https://yoursite.com/wp-content/debug.log فایل را به‌صورت متن ساده برمی‌گرداند. لاگ‌های دیباگ حاوی مسیرهای مطلق سرور، جزئیات درونی افزونه‌ها و قالب‌ها، خطاهای پایگاه داده با متن واقعی کوئری و گاهی مقادیری هستند که به توابع ناموفق پاس داده شده‌اند. این یعنی شناسایی رایگان برای هرکسی که نشانی را حدس بزند — و این یکی از اولین نشانی‌هایی است که اسکنرهای خودکار امتحان می‌کنند.

دو راه برای برخورد با آن هست. راه بهتر جابه‌جا کردن لاگ است.

لاگ را با یک مسیر جابه‌جا کنید

از وردپرس ۵.۱ به بعد، WP_DEBUG_LOG به‌جای مقدار بولی یک مسیر فایل رشته‌ای هم می‌پذیرد. آن را به جایی بیرون از ریشه سند نشانه بگیرید:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/home/youruser/logs/wp-errors.log' );
define( 'WP_DEBUG_DISPLAY', false );

سه قاعده برای آن مسیر. از مسیر مطلق استفاده کنید — مسیر نسبی نسبت به دایرکتوری کاری PHP حل می‌شود که در هر درخواست و هر سرور فرق می‌کند، پس ردّ فایل را گم خواهید کرد. آن دایرکتوری باید از قبل وجود داشته باشد؛ PHP آن را نمی‌سازد و اگر نتواند فایل را باز کند بی‌سروصدا شکست می‌خورد. و دایرکتوری باید برای کاربر PHP قابل نوشتن باشد، که روی هاست اشتراکی همان حسابی نیست که با آن از طریق SFTP وارد می‌شوید.

اگر هاست شما را به ریشه وب محدود کرده و جایی بالاتر از آن برای نوشتن نیست، مسیر پیش‌فرض را نگه دارید و به‌جایش دسترسی را در سطح سرور مسدود کنید. روی Apache:

<Files "debug.log">
  Require all denied
</Files>

این در فایل .htaccess داخل wp-content می‌رود، نه فایل ریشه — وردپرس هنگام ذخیره پیوندهای یکتا فایل .htaccess ریشه را بازنویسی می‌کند و می‌تواند افزوده شما را پاک کند. روی nginx، فایل .htaccess اصلاً کاری نمی‌کند؛ به یک بلوک location در پیکربندی سرور نیاز دارید که روی هاست مدیریت‌شده معمولاً یعنی درخواست از پشتیبانی.

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

خواندن و دنبال کردن زنده فایل

با SSH، هم‌زمان با بازتولید باگ آن را زنده ببینید:

tail -f wp-content/debug.log

خطا را در یک تب دیگر بازتولید کنید و خط‌های تازه همان‌طور که نوشته می‌شوند ظاهر می‌شوند. برای دیدن فقط اتفاق‌های اخیر، یا فیلتر کردن روی یک افزونه:

tail -n 100 wp-content/debug.log
grep -i 'plugin-slug' wp-content/debug.log | tail -n 50

PHP به انتهای فایل اضافه می‌کند، پس از پایین به بالا بخوانید. هر ورودی با زمان UTC مهر خورده که با تنظیم منطقه زمانی وردپرس شما یکی نیست — نگذارید این موضوع باعث شود فکر کنید دارید ورودی‌های قدیمی را می‌بینید.

با WP-CLI می‌توانید این ثابت‌ها را بدون ویرایش دستی فایل تغییر دهید:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

پرچم --raw اهمیت دارد — بدون آن مقدار به‌صورت رشته "true" نوشته می‌شود نه مقدار بولی. برای حالت مسیر، --raw را حذف کنید تا به‌صورت یک رشته داخل گیومه نوشته شود.

بدون SSH؟ فایل را با SFTP دانلود کنید یا در فایل منیجر هاست بازش کنید. از افزونه‌هایی که لاگ را داخل wp-admin نشان می‌دهند پرهیز کنید مگر اینکه کاملاً به آن‌ها اعتماد داشته باشید؛ دارید به یک افزونه دسترسی خواندن به فایلی پر از جزئیات درونی سرور می‌دهید.

اگر بلوک دقیق wp-config متناسب با پیکربندی خودتان را می‌خواهید، همراه با یک مسیر امن بیرون از ریشه و قانون سرور متناظرش، سازنده لاگ دیباگ وردپرس آن را برایتان می‌سازد.

وقتی کارتان تمام شد خاموشش کنید

هیچ چیزی در هسته وردپرس فایل debug.log را نمی‌چرخاند یا کوتاه نمی‌کند. روی سایتی که در هر بار بارگذاری صفحه یک نوتیس می‌دهد، این فایل بی‌حدومرز بزرگ می‌شود و می‌تواند دیسک را پر کند — که سایت را بدتر از باگی که دنبالش بودید از دسترس خارج می‌کند. ثبت لاگ را روشن کنید، مشکل را بازتولید کنید، لاگ را بخوانید و بعد WP_DEBUG را دوباره روی false بگذارید.

برای خالی کردن فایل بدون حذف کردنش:

: > wp-content/debug.log

وقتی لاگ خالی می‌ماند

این موارد را به‌ترتیب بررسی کنید. مقدار WP_DEBUG برابر false است — رایج‌ترین دلیل به‌تنهایی، و بی‌سروصدا همه‌چیز دیگر را غیرفعال می‌کند. ثابت زیر خط «stop editing» است در wp-config.php. دسترسی‌های فایل — PHP نمی‌تواند در wp-content یا در دایرکتوری سفارشی که مشخص کرده‌اید بنویسد. یک خطای مهلک پیش از تمام‌شدن بارگذاری wp-config، مثل یک خطای نحوی در خود فایل پیکربندی، آن‌قدر زود رخ می‌دهد که ثبت لاگ وردپرس نمی‌تواند بگیردش؛ این‌ها به‌جایش به لاگ خطای PHP خود سرور می‌روند. هاست شما آن را بازنویسی می‌کند — بعضی پلتفرم‌های مدیریت‌شده تنظیم error_log در PHP را ثابت می‌کنند یا لاگ‌ها را به داشبورد خودشان می‌فرستند؛ در این حالت ثابت‌های شما درست تنظیم شده‌اند و خروجی صرفاً جای دیگری است. پیش از آنکه فرض کنید پیکربندی‌تان خراب است، نمایشگر لاگ هاست را بررسی کنید.