מיקום יומן הדיבאג של WordPress: איפה debug.log נמצא ואיך מעבירים אותו

‏WordPress כותב את יומן הדיבאג שלו אל 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. */. כל מה שמתווסף מתחת לשורה הזו רץ אחרי ש-WordPress כבר עלה, ולכן מתעלמים ממנו.

קבוע	ברירת מחדל	מה הוא עושה
WP_DEBUG	false	מתג ראשי. מעלה את רמת דיווח השגיאות של PHP כך שיוצגו התראות, אזהרות והודעות על פונקציות מיושנות. שום דבר אחר ברשימה הזו לא עובד בלעדיו.
WP_DEBUG_LOG	false	שולח שגיאות לקובץ. הערך true פירושו wp-content/debug.log. מחרוזת נחשבת לנתיב הקובץ שאליו לכתוב.
WP_DEBUG_DISPLAY	true	מדפיס שגיאות לתוך ה-HTML של העמוד, גלוי לכל מבקר.

התלות היא החלק שאנשים טועים בו. הקבוע WP_DEBUG_LOG נקרא בתוך הענף של WP_DEBUG בקוד האתחול של WordPress. אם 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 חייב להיות false בסביבת ייצור

כשהתצוגה פעילה, שגיאות PHP מודפסות לתוך תשובת ה-HTML. התראה אחת על פונקציה מיושנת בערכת עיצוב מדפיסה את הנתיב המוחלט של השרת שלכם לכל מבקר. שגיאת מסד נתונים מדפיסה שמות טבלאות וקטעי שאילתות. גרוע מכך, פלט שמופיע לפני שליחת הכותרות שובר הפניות, שובר תשובות REST ו-AJAX שמצפות ל-JSON נקי, ויכול לייצר את המסך הלבן שאנשים מאשימים אחר כך תוסף כלשהו בגללו.

דקוּת אחת שכדאי להכיר: הגדרת WP_DEBUG_DISPLAY כ-null אינה זהה ל-false. הערך null אומר ל-WordPress להשאיר את הגדרת display_errors של PHP כמו שהיא ולרשת את מה שהשרת קבע. הערך false מכבה אותה באופן אקטיבי. באתר בסביבת ייצור השתמשו ב-false והוסיפו את שורת ה-ini_set שלמעלה כרשת ביטחון נוספת, כי תוסף יכול להחזיר את display_errors למצב פעיל בשלב מאוחר יותר של הבקשה.

מיקום ברירת המחדל ניתן להורדה על ידי כל אחד

הקובץ wp-content/debug.log יושב בתוך שורש האתר. שום דבר בהתקנת WordPress סטנדרטית לא חוסם בקשות ישירות אליו. בהתקנת Apache או nginx טיפוסית, הכתובת https://yoursite.com/wp-content/debug.log מחזירה את הקובץ כטקסט רגיל. יומני דיבאג מכילים נתיבי שרת מוחלטים, פנימיוּת של תוספים וערכות עיצוב, שגיאות מסד נתונים עם טקסט שאילתה אמיתי, ולפעמים ערכים שהועברו דרך פונקציות שנכשלו. זה מודיעין חינם לכל מי שמנחש את הכתובת — וזו אחת הכתובות הראשונות שסורקים אוטומטיים מנסים.

יש שתי דרכים להתמודד עם זה. הטובה מביניהן היא להעביר את היומן.

העברת היומן באמצעות נתיב

החל מ-WordPress 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, לא לזה שבשורש — ‏WordPress כותב מחדש את .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, שלא תתאים להגדרת אזור הזמן של WordPress שלכם — אל תיתנו לזה לגרום לכם לחשוב שאתם מסתכלים על רשומות ישנות.

עם 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 המדויק להתקנה שלכם, כולל נתיב בטוח מחוץ לשורש האתר וכלל השרת התואם, מחולל יומן הדיבאג של WordPress יבנה אותו בשבילכם.

כבו את זה כשסיימתם

שום דבר בליבת WordPress לא מסובב או מקצץ את debug.log. באתר שזורק התראה בכל טעינת עמוד, הקובץ גדל בלי גבול ויכול למלא את הדיסק — מה שמפיל את האתר בצורה חמורה יותר מהבאג שרדפתם אחריו. הפעילו רישום, שחזרו את הבעיה, קראו את היומן, ואז החזירו את WP_DEBUG ל-false.

כדי לרוקן את הקובץ בלי למחוק אותו:

: > wp-content/debug.log

כשהיומן נשאר ריק

עברו על אלה לפי הסדר. WP_DEBUG מוגדר כ-false — הסיבה הנפוצה ביותר, והיא מנטרלת בשקט את כל השאר. הקבוע נמצא מתחת לשורת ה-”stop editing” בקובץ wp-config.php. הרשאות קבצים — ‏PHP לא מצליח לכתוב אל wp-content, או אל התיקייה המותאמת שציינתם. שגיאה פטאלית לפני ש-wp-config מסיים להיטען, למשל שגיאת תחביר בקובץ התצורה עצמו, מתרחשת מוקדם מדי מכדי שמנגנון הרישום של WordPress יתפוס אותה; אלה הולכות ליומן שגיאות ה-PHP של השרת עצמו. חברת האחסון דורסת את ההגדרה — חלק מהפלטפורמות המנוהלות מקבעות את הגדרת error_log של PHP או מנתבות את הרישום ללוח הבקרה שלהן, ובמקרה כזה הקבועים שלכם מוגדרים נכון והפלט פשוט נמצא במקום אחר. בדקו את מציג היומנים של חברת האחסון לפני שאתם מניחים שהתצורה שלכם שבורה.