Emplacement du debug log WordPress : où se trouve debug.log et comment le déplacer

WordPress écrit son journal de débogage dans wp-content/debug.log par défaut — soit un chemin absolu du type /chemin/vers/votre/site/wp-content/debug.log sur le disque. Le fichier n’existe pas tant que rien n’a été journalisé, et il n’est écrit que si WP_DEBUG vaut true et que WP_DEBUG_LOG est activé dans wp-config.php. Cet emplacement par défaut pose aussi un vrai problème de sécurité, car sur la plupart des hébergements n’importe qui peut le récupérer depuis un navigateur.

Les trois constantes et le rôle de chacune

Les trois se placent dans wp-config.php, au-dessus de la ligne qui indique /* That's all, stop editing! Happy blogging. */. Tout ce qui est ajouté sous cette ligne s’exécute après le démarrage de WordPress et se retrouve ignoré.

Constante	Défaut	Rôle
WP_DEBUG	false	Interrupteur principal. Relève le niveau de rapport d’erreurs PHP pour afficher notices, avertissements et dépréciations. Rien d’autre dans cette liste ne fonctionne sans elle.
WP_DEBUG_LOG	false	Envoie les erreurs vers un fichier. true signifie wp-content/debug.log. Une chaîne est interprétée comme le chemin du fichier à écrire.
WP_DEBUG_DISPLAY	true	Affiche les erreurs dans le HTML de la page, visibles par tous les visiteurs.

La dépendance entre elles est ce que les gens comprennent de travers. WP_DEBUG_LOG est lue à l’intérieur de la branche WP_DEBUG du code de démarrage de WordPress. Si WP_DEBUG vaut false, mettre WP_DEBUG_LOG à true ne fait strictement rien — pas de fichier, pas d’erreur, pas d’avertissement. Si vous avez ajouté WP_DEBUG_LOG et qu’aucun journal n’apparaît, vérifiez WP_DEBUG en premier.

Une configuration qui fonctionne sur un site en production :

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

Si WP_DEBUG est déjà définie plus haut dans le fichier — c’est généralement le cas, à false — modifiez cette ligne existante plutôt que d’ajouter un second define(). Définir deux fois la même constante déclenche un avertissement PHP qui, sur un site où l’affichage est actif, atterrit tout en haut de votre page.

Pourquoi WP_DEBUG_DISPLAY doit être à false en production

Avec l’affichage activé, les erreurs PHP sont écrites dans la réponse HTML. Une simple notice de dépréciation émise par un thème affiche le chemin absolu de votre serveur à tous les visiteurs. Une erreur de base de données affiche les noms de tables et des fragments de requêtes. Pire, une sortie émise avant l’envoi des en-têtes casse les redirections, casse les réponses REST et AJAX qui attendent du JSON propre, et peut produire cette page blanche qu’on attribue ensuite à une extension.

Une subtilité à connaître : mettre WP_DEBUG_DISPLAY à null n’équivaut pas à false. null indique à WordPress de ne pas toucher au réglage display_errors de PHP et d’hériter de ce que le serveur a configuré. false le force activement à off. Sur un site en production, utilisez false et ajoutez la ligne ini_set ci-dessus comme ceinture et bretelles, puisqu’une extension peut réactiver display_errors plus tard dans la requête.

L’emplacement par défaut est récupérable publiquement

wp-content/debug.log se trouve à l’intérieur de la racine web. Rien dans une installation WordPress standard ne bloque les requêtes directes vers ce fichier. Sur une configuration Apache ou nginx classique, https://votresite.com/wp-content/debug.log renvoie le fichier en texte brut. Les journaux de débogage contiennent des chemins serveur absolus, les rouages internes de vos extensions et de votre thème, des erreurs de base de données avec le texte réel des requêtes, et parfois des valeurs passées à des fonctions en échec. C’est de la reconnaissance offerte à quiconque devine l’URL — et c’est l’une des premières URL que testent les scanners automatisés.

Deux façons de traiter le problème. La meilleure consiste à déplacer le journal.

Déplacer le journal avec un chemin

Depuis WordPress 5.1, WP_DEBUG_LOG accepte une chaîne de caractères contenant un chemin de fichier au lieu d’un booléen. Pointez-la vers un emplacement hors de la racine du document :

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

Trois règles pour ce chemin. Utilisez un chemin absolu — un chemin relatif est résolu par rapport au répertoire de travail de PHP, qui varie d’une requête et d’un serveur à l’autre, et vous perdrez la trace du fichier. Le répertoire doit déjà exister ; PHP ne le créera pas, et s’il ne peut pas ouvrir le fichier il échoue silencieusement. Et le répertoire doit être accessible en écriture par l’utilisateur PHP, qui sur un hébergement mutualisé n’est pas le même compte que celui de votre connexion SFTP.

Si votre hébergement vous cantonne à la racine web et qu’il n’y a nulle part au-dessus où écrire, gardez le chemin par défaut et bloquez plutôt l’accès au niveau du serveur. Apache :

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

Cela va dans un fichier .htaccess situé dans wp-content, pas dans celui de la racine — WordPress réécrit le .htaccess racine quand vous enregistrez les permaliens et peut effacer votre ajout. Sur nginx, .htaccess ne sert absolument à rien ; il faut un bloc location dans la configuration du serveur, ce qui en hébergement infogéré revient généralement à passer par le support.

Soyons honnêtes sur ce que le blocage vous apporte : le fichier reste sur le disque, dans un répertoire servi par le serveur web. Une faille de traversée de répertoire dans n’importe quelle extension permet encore de le lire. Le sortir de la racine web est la correction la plus solide.

Lire et suivre le fichier

En SSH, suivez-le en direct pendant que vous reproduisez le bug :

tail -f wp-content/debug.log

Reproduisez l’erreur dans un autre onglet et les nouvelles lignes apparaissent au fur et à mesure de leur écriture. Pour ne voir que ce qui vient de se passer, ou pour filtrer sur une seule extension :

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

PHP ajoute à la fin du fichier, donc lisez de bas en haut. Chaque entrée est horodatée en UTC, ce qui ne correspondra pas au fuseau horaire réglé dans WordPress — ne vous laissez pas croire que vous regardez de vieilles entrées.

Avec WP-CLI, vous pouvez basculer ces constantes sans éditer le fichier à la main :

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

Le drapeau --raw compte : sans lui, la valeur est écrite sous forme de chaîne "true" et non de booléen. Pour la forme avec chemin, omettez --raw afin qu’elle soit écrite comme une chaîne entre guillemets.

Pas de SSH ? Téléchargez le fichier en SFTP ou ouvrez-le dans le gestionnaire de fichiers de votre hébergeur. Évitez les extensions qui affichent le journal dans wp-admin, sauf si vous leur faites entièrement confiance : vous accordez à une extension un accès en lecture à un fichier rempli de détails internes de votre serveur.

Si vous voulez le bloc wp-config exact pour votre configuration, avec un chemin sûr hors de la racine et la règle serveur correspondante, le générateur de debug log WordPress le construira pour vous.

Désactivez-le une fois terminé

Rien dans le cœur de WordPress ne fait de rotation ni de purge de debug.log. Sur un site qui émet une notice à chaque chargement de page, le fichier grossit sans limite et peut saturer le disque — ce qui met le site à terre bien plus durement que le bug que vous poursuiviez. Activez la journalisation, reproduisez le problème, lisez le journal, puis remettez WP_DEBUG à false.

Pour vider le fichier sans le supprimer :

: > wp-content/debug.log

Quand le journal reste vide

Passez ces points en revue dans l’ordre. WP_DEBUG est à false — la cause de loin la plus fréquente, et elle désactive silencieusement tout le reste. La constante est placée sous la ligne « stop editing » dans wp-config.php. Les permissions de fichiers — PHP ne peut pas écrire dans wp-content, ni dans le répertoire personnalisé que vous avez indiqué. Une erreur fatale survenue avant la fin du chargement de wp-config, par exemple une erreur de syntaxe dans le fichier de configuration lui-même, se produit trop tôt pour que la journalisation WordPress l’attrape ; celles-là partent dans le journal d’erreurs PHP du serveur. Votre hébergeur impose sa configuration — certaines plateformes infogérées figent le réglage error_log de PHP ou redirigent la journalisation vers leur propre tableau de bord, auquel cas vos constantes sont correctes et la sortie se trouve simplement ailleurs. Consultez le visualiseur de journaux de l’hébergeur avant de conclure que votre configuration est cassée.