Un sito WordPress che mostra una pagina bianca, un errore critico o un modulo bloccato può fermare contatti, richieste di preventivo e vendite. Il debug WordPress è una procedura tecnica, mentre la modalita di debug serve a raccogliere e interpretare gli errori.
Non basta disattivare plugin a caso. Devi raccogliere l’errore, individuare il file coinvolto e verificare la correzione. Ecco una procedura pratica, utile anche se la bacheca non è più accessibile.
Punti chiave per intervenire senza peggiorare il problema
- Crea sempre un backup completo di file e database prima di modificare configurazioni, plugin o tema.
- Attiva il debug per un periodo limitato e salva gli errori nel file
debug.log. - Su un sito pubblico, nascondi gli errori dal front-end. I visitatori non devono vedere percorsi file, messaggi PHP o dettagli del server.
- Leggi il log partendo dalle righe più recenti e cerca il primo errore fatale, non l’ultimo avviso comparso.
- Se il sito è irraggiungibile, isola prima plugin e tema. Non modificare dieci elementi insieme.
- Quando il problema è risolto, disattiva il debug e conserva una nota con causa, intervento e versione ripristinata.
Un backup mai provato con un ripristino reale non è una garanzia. È una speranza.
Prima del debug: backup, staging e accessi
Il debug è utile, ma una modifica frettolosa può creare un secondo problema. Prima verifica l’accesso al backend di WordPress, al pannello hosting e ai file tramite il file manager dell’hosting, un client FTP o SFTP. Tieni anche una copia recente del sito.
Lavora su staging quando il sito genera contatti
Un aggiornamento può rompere un form, una pagina servizi, un checkout WooCommerce o un’integrazione con le email. Se il sito è online e porta lavoro ogni giorno, prova prima modifiche e aggiornamenti in un ambiente staging per WordPress.
Lo staging è una copia separata, cioè uno staging environment. Qui puoi attivare i log, aggiornare plugin e testare codice PHP senza esporre errori ai clienti. Proteggilo con password e impostalo come noindex.
Segna cosa è cambiato poco prima dell’errore
Un sito spesso smette di funzionare dopo un aggiornamento di WordPress, del tema, di un plugin o della versione PHP. Annota data, ora e sintomo: pagina bianca, errore 500, lentezza, login bloccato, form che non invia email.
Controlla anche cache del browser, CDN, plugin cache e cache server. Una pagina obsoleta in cache può sembrare un errore di WordPress, ma non esserlo.
Come attivare il debug WordPress in wp-config.php
Per attivare il debug WordPress devi modificare il file wp-config.php, disponibile nella cartella principale dell’installazione. Puoi farlo con il file manager dell’hosting oppure via SFTP.
Inserisci le costanti nel punto corretto
Apri wp-config.php con un editor di testo semplice. Inserisci queste righe dopo le impostazioni del database e delle chiavi di sicurezza, ma prima della riga:
/* That's all, stop editing! Happy publishing. */
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Salva il file e ripeti l’azione che genera il problema. WP_DEBUG abilita la modalità di raccolta degli errori. Con WP_DEBUG_LOG attivo, il log viene scritto in wp-content/debug.log.
Non mostrare PHP errors ai visitatori
WP_DEBUG_DISPLAY impostato su false evita che errori, avvisi e percorsi interni compaiano nel codice della pagina. La direttiva PHP display_errors può influire sulla visualizzazione lato server, ma nessun errore PHP, o PHP errors, deve essere mostrato ai visitatori di un sito in produzione.
Mostrare un errore PHP non aiuta il cliente. Può trasmettere poca affidabilità e rivelare dettagli utili a chi cerca vulnerabilità. La configurazione con log attivo e visualizzazione disattivata è la più prudente durante un controllo rapido in produzione.
Se il log WordPress non è sufficiente, confrontalo con quello PHP del server tramite error_log. Il percorso dipende dall’hosting e dalla configurazione del server.
I debugging plugins, come WP Debugging, possono semplificare l’attivazione delle costanti. Per un controllo tecnico affidabile, però, resta essenziale conoscere il file di configurazione principale.
Le costanti di debug che servono davvero
La documentazione ufficiale sul debugging WordPress descrive le costanti principali del WordPress debugging. Non attivarle tutte senza motivo. Ogni opzione raccoglie informazioni diverse e alcune incidono sulle performance.
WP_DEBUG, WP_DEBUG_LOG e WP_DEBUG_DISPLAY
WP_DEBUG abilita la modalità di debug. Da solo può mostrare errori PHP, notice, warning ed error notices, aiutando a distinguere gli avvisi dagli errori fatali.
WP_DEBUG_LOG registra gli errori nel file /wp-content/debug.log. È utile quando il problema non appare sempre o riguarda solo alcune pagine. Controlla anche error_log, il file PHP del server, che può contenere informazioni complementari rispetto a debug.log.
WP_DEBUG_DISPLAY decide se gli errori vengono stampati nell’HTML. Mantienilo su false sul sito live. Il log conserva ciò che serve, senza esporre messaggi tecnici al pubblico.
SCRIPT_DEBUG per CSS e JavaScript
SCRIPT_DEBUG forza WordPress a caricare versioni non minificate dei file CSS e JavaScript del core. È utile se un menu non risponde, l’editor ha comportamenti strani o una funzione JavaScript va in errore.
Aggiungi questa riga solo durante il test:
define( 'SCRIPT_DEBUG', true );
Non risolve un conflitto. Ti aiuta a vedere file più leggibili durante l’analisi.
SAVEQUERIES e rallentamenti del database
SAVEQUERIES salva ogni query verso il database MySQL, il tempo impiegato e la funzione che l’ha chiamata. Può evidenziare plugin o codice personalizzato inefficienti, con interrogazioni eccessive.
define( 'SAVEQUERIES', true );
Questa opzione crea overhead e può peggiorare la site performance durante la raccolta delle query. Usala solo per una diagnosi breve, preferibilmente in staging, poi rimuovila. Un sito lento non ha bisogno di più dati raccolti senza criterio, ma della causa corretta.
Come leggere debug.log senza perdersi tra gli avvisi
Un debug.log può contenere centinaia di righe. Non tutte hanno la stessa gravità. Parti dalle righe create nell’orario esatto in cui hai riprodotto il problema.
Se l’azione non viene registrata, verifica che WP_DEBUG sia impostato su true e che WP_DEBUG_LOG sia attivo. Per un troubleshooting ordinato, confronta anche il log PHP del server o l’output prodotto da error_log.
Individua tipo, file e riga dell’errore
Una riga del log indica di solito data, tipo di errore, percorso del file e numero di riga. Gli error messages vanno interpretati insieme a tutti questi dati, non isolatamente.
Gli errori PHP, o PHP errors, più importanti sono spesso Fatal error, Uncaught Error e Parse error. Un warning non blocca sempre il sito. Un fatal error sì. Cerca il primo errore fatale comparso dopo aver aperto la pagina problematica. Il file indicato può appartenere a un plugin, al tema o a una funzione personalizzata.
Distingui la causa dal sintomo
Se il log cita un file dentro wp-content/plugins/nome-plugin/, quel plugin è il primo sospettato. Se il percorso è nel tema attivo, verifica template, funzioni aggiunte e compatibilità PHP.
Un messaggio relativo alla memoria PHP può essere un sintomo. Prima di aumentare il limite, controlla se un plugin ripete richieste, query o operazioni pesanti. Per approfondire la gestione di errori, conflitti e aggiornamenti, consulta la guida all’assistenza WordPress per PMI.
White Screen of Death: recuperare un sito bloccato
La White Screen of Death è una pagina bianca senza contenuto. Può dipendere da un errore PHP fatale, un plugin incompatibile, un tema difettoso o memoria insufficiente. In questi casi, non disattivare l’error handling senza una diagnosi in ambiente controllato.
Non iniziare modificando file del core WordPress. La guida ufficiale agli errori comuni indica di controllare prima plugin e tema.
Disattiva i plugin via FTP o file manager
Se non riesci ad accedere a wp-admin, il backend di WordPress potrebbe essere irraggiungibile anche quando i file sono ancora accessibili. Entra quindi nei file del sito tramite FTP o file manager e rinomina la cartella:
wp-content/plugins
Ad esempio, trasformala in plugins_old. WordPress non troverà più i plugin e li disattiverà tutti temporaneamente. Se il sito torna online, ripristina il nome originale della cartella.
Poi riattiva gli active plugins uno alla volta dalla bacheca. Dopo ogni riattivazione, controlla homepage, pagina contatti, area riservata e funzioni commerciali importanti.
Se il problema resta, prova il tema e chiedi supporto hosting
Se la pagina bianca continua, passa temporaneamente a un tema predefinito di WordPress, se disponibile. Controlla anche gli error log PHP del server, spesso raccolti nel file error_log, e la versione PHP configurata dall’hosting. Questi log sono distinti da quelli gestiti da WordPress.
Evita modifiche dirette al database per disattivare estensioni se non sai esattamente cosa stai facendo. Un valore errato può compromettere impostazioni, ruoli utenti o dati serializzati. Se SFTP non è disponibile, chiedi al supporto hosting di ripristinare l’accesso ai file o verificare il log server. Quando il sito è completamente irraggiungibile, non affidarti ai debugging plugins per risolvere il problema.
Dopo la correzione: controlli tecnici e sicurezza
Un sito che torna online non è automaticamente risolto. Verifica form, login, checkout, email, pagine dei servizi e tracciamenti pubblicitari.
Disattiva il debug appena finito
Al termine dell’analisi, modifica di nuovo wp-config.php:
define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
Rimuovi anche SAVEQUERIES e SCRIPT_DEBUG se li hai aggiunti per il test. Conserva i log, incluso error_log, solo per il tempo necessario e proteggili da accessi non autorizzati. Se servono per un’analisi successiva, non cancellarli automaticamente.
Trasforma l’errore in manutenzione preventiva
Aggiorna core, tema e plugin dopo un backup verificato. Elimina le estensioni inutilizzate e gli account amministratore che non servono. Controlla ogni mese log, uptime, sicurezza e funzionamento di form, login, checkout, email e tracciamenti.
La manutenzione tecnica del sito web evita che un piccolo avviso diventi una pagina irraggiungibile nel momento peggiore. Per un sito aziendale, il monitoraggio non è un extra. È parte del lavoro.
Domande frequenti sul debug WordPress
Dove si trova il file debug.log?
Con WP_DEBUG_LOG attivo, WordPress salva normalmente gli errori nel percorso /wp-content/debug.log. Devi avere anche WP_DEBUG impostato su true.
Posso lasciare WP_DEBUG attivo sul sito online?
Solo per il tempo necessario a una verifica mirata. Mantieni WP_DEBUG_DISPLAY su false, risolvi il problema e poi disattiva il debug.
Perché il debug non mostra errori a schermo?
Controlla WP_DEBUG_DISPLAY, la cache e la configurazione dell’hosting. In alcuni ambienti di sviluppo può essere utile impostare WP_DISABLE_FATAL_ERROR_HANDLER su true per vedere gli errori fatali.
Il log deve guidare ogni intervento
Il debug WordPress non è una soluzione automatica. È il modo più rapido per smettere di ipotizzare e iniziare a verificare.
Attiva i log, isola la causa, testa la correzione e spegni tutto quando il sito torna stabile. Un sito aziendale affidabile nasce anche da queste procedure, spesso invisibili, ma decisive quando arrivano contatti e richieste.
