مكان سجل التتبع في ووردبريس: أين يوجد 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، فضبط WP_DEBUG_LOG على true لا يفعل شيئاً على الإطلاق — لا ملف، ولا خطأ، ولا تحذير. وإذا أضفت 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 معطلاً في الإنتاج

مع تفعيل العرض، تُطبع أخطاء 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 الملف كنص عادي. وسجلات التتبع تحتوي على مسارات مطلقة على الخادم، وتفاصيل داخلية عن الإضافات والقوالب، وأخطاء قاعدة بيانات بنص الاستعلام الحقيقي، وأحياناً قيماً مررت عبر دوال فاشلة. وهذا استطلاع مجاني لأي شخص يخمّن الرابط — وهو من أوائل الروابط التي تجرّبها أدوات الفحص الآلية.

وأمامك طريقتان للتعامل مع ذلك. الأفضل منهما هو نقل السجل.

انقل السجل عبر تحديد مسار

منذ ووردبريس 5.1، يقبل 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 أو توجّه التسجيل إلى لوحتها الخاصة، وعندها تكون ثوابتك مضبوطة بشكل صحيح والمخرجات ببساطة في مكان آخر. راجع عارض السجلات لدى مضيفك قبل أن تفترض أن إعدادك معطوب.