Modalità debug di WordPress spiegata semplice

Quando qualcosa non funziona, WordPress può dirti esattamente cosa: basta attivare la modalità debug. In questo articolo vediamo come farlo in modo sicuro, dove leggere gli errori e quali strumenti usare senza mettere le mani nel codice.

Per impostazione predefinita WordPress nasconde i messaggi di errore tecnici, per non mostrarli ai visitatori. È la scelta giusta per un sito online, ma diventa un ostacolo quando qualcosa si rompe e non si capisce perché. La modalità debug serve esattamente a questo: far emergere gli errori in modo controllato, così da poterli leggere e risolvere.

Un’avvertenza prima di iniziare

La modalità debug è uno strumento di diagnosi, non un’impostazione da lasciare attiva e visibile su un sito di produzione. Mostrare gli errori ai visitatori, infatti, può rivelare informazioni sensibili sulla struttura del sito, ed è uno dei motivi per cui, parlando di hardening, si raccomanda di tenere disattivata la visualizzazione degli errori in produzione.

La soluzione, come vedremo, è semplice: si attiva il debug registrando gli errori in un file privato, senza mostrarli sulla pagina. E quando si è finito, lo si disattiva.

Attivare il debug in modo sicuro

Il debug si controlla da tre costanti nel file wp-config.php. La configurazione consigliata, sicura anche su un sito online, è questa:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

In breve: WP_DEBUG è l’interruttore generale che attiva la segnalazione degli errori; WP_DEBUG_LOG fa sì che gli errori vengano scritti in un file di log invece che (o oltre che) a schermo; WP_DEBUG_DISPLAY impostato su false evita che gli errori compaiano sulle pagine viste dai visitatori. Queste righe vanno inserite prima del commento che indica di interrompere le modifiche, verso la fine del file wp-config.php.

Dove trovare gli errori: il file debug.log

Con WP_DEBUG_LOG attivo, WordPress raccoglie gli errori in un file chiamato debug.log, che si trova nella cartella wp-content del sito. Lo si apre collegandosi via FTP (o dal file manager dell’hosting) e leggendolo come un normale file di testo.

Ogni riga riporta data, tipo di errore e, soprattutto, il file e la riga di codice che lo hanno generato: è proprio questa informazione che permette di capire quale plugin, tema o funzione è all’origine del problema. Spesso, leggere le ultime righe del log subito dopo che l’errore si è verificato è sufficiente per individuare la causa.

Strumenti utili senza toccare il codice

Non sempre serve modificare wp-config.php. WordPress include una sezione Salute del sito (Site Health), raggiungibile da Strumenti → Salute del sito, che segnala automaticamente diversi problemi comuni: una versione di PHP obsoleta, moduli mancanti o configurazioni poco sicure. È un ottimo punto di partenza per una diagnosi rapida.

Per chi vuole qualcosa di più, due plugin gratuiti sono molto usati. Query Monitor mostra in dettaglio le query al database, errori PHP, hook, script e chiamate esterne: è lo strumento di riferimento per capire cosa succede “sotto il cofano” di una pagina. Health Check & Troubleshooting consente invece di attivare una modalità di risoluzione dei problemi che disabilita temporaneamente plugin e tema solo per te, senza toccare ciò che vedono i visitatori: utilissimo per isolare un conflitto su un sito live.

Usare il debug per trovare la causa

Messi insieme questi strumenti, la diagnosi diventa metodica. Di fronte a un errore, l’approccio tipico è: attivare il debug con scrittura su log, riprodurre il problema e leggere nel debug.log quale file viene segnalato. Se il file appartiene a un plugin o a un tema, hai individuato il responsabile e puoi disattivarlo o aggiornarlo. È lo stesso ragionamento per esclusione che abbiamo visto nell’articolo sugli errori comuni di WordPress, ma con in più l’informazione precisa che il log ti fornisce.

Ricordati di disattivarlo

Quando hai finito, riporta le costanti allo stato iniziale (o imposta WP_DEBUG su false) ed elimina il file debug.log se contiene informazioni che non vuoi lasciare sul server. Lasciare il debug attivo a lungo non è pericoloso quanto mostrarlo ai visitatori, ma un log che cresce indefinitamente occupa spazio e non serve a nessuno una volta risolto il problema.

Prossimi passi

La modalità debug è il filo che collega tutti gli altri articoli di questa sezione: è lo strumento che trasforma un errore misterioso in un messaggio leggibile. Se stai affrontando un problema specifico, parti dagli errori comuni di WordPress, dai problemi di login o dalle modifiche che non si vedono, e tieni il debug a portata di mano come prima mossa diagnostica.

Dennis è uno sviluppatore Open Source appassionato di WordPress, con esperienza in soluzioni enterprise e plugin personalizzati. Vive in Italia, è madrelingua tedesco e parla fluentemente italiano, un ponte naturale tra culture e community diverse. Contribuisce attivamente a progetti Open Source e co-organizza il WordPress Meetup di Milano.