Risolvere il mancato caricamento dell'editor a blocchi di WordPress

Nella maggior parte dei casi, un editor a blocchi di WordPress che non si carica è colpa di un errore JavaScript: uno script rotto di un plugin o di un tema blocca l’intera app React e l’editor non arriva mai a completare il rendering. Apri la console per sviluppatori del browser (F12, oppure Cmd+Opzione+I su Mac), ricarica la schermata di modifica e leggi l’errore in rosso. Quasi sempre indica il nome del file che ha generato l’eccezione. Quella singola riga ti dice quale plugin disattivare e di solito ti riporta a scrivere in meno di cinque minuti. Reinstallare WordPress, alzare il memory_limit di PHP e passare all’editor classico (Classic Editor) sono i tre suggerimenti più diffusi online, e tutti e tre sono quasi sempre la mossa sbagliata.

Perché l’editor si rompe nel modo in cui si rompe

L’editor a blocchi (Gutenberg) è un’applicazione React a pagina singola che gira dentro wp-admin/post.php e post-new.php. WordPress accoda una serie di pacchetti di script — wp-blocks, wp-element, wp-editor, wp-edit-post — e l’app si inizializza tramite wp.domReady(). JavaScript smette di eseguire alla prima eccezione non gestita. Quindi, se uno qualsiasi degli script accodati genera un’eccezione mentre l’editor si sta inizializzando, tutto ciò che viene dopo muore con esso. La tua area di scrittura, costruita con cura, collassa in un riquadro bianco vuoto o nel messaggio “L’editor ha riscontrato un errore imprevisto”.

Per impostazione predefinita WordPress concatena anche gli script dell’area di amministrazione in un numero ridotto di richieste. Questo significa che il JS rotto di un plugin può trascinare a fondo altri script non correlati caricati nello stesso bundle, ed è per questo che il colpevole non è sempre ovvio dal solo comportamento. La console invece lo è.

Il secondo tipo di guasto si presenta diversamente: l’editor si carica, ma il salvataggio genera “Aggiornamento non riuscito. La risposta non è una risposta JSON valida.” Questo non è un problema di JavaScript. L’editor dialoga con la REST API su /wp-json/wp/v2/ e si aspetta di ricevere in risposta del JSON pulito. Se un plugin o il functions.php del tuo tema emette un notice, un warning o un errore fatale di PHP prima del JSON — oppure un plugin di sicurezza blocca la route REST, o un plugin di redirect riscrive l’URL — la risposta risulta inquinata e l’editor non riesce ad analizzarla.

Come risolverlo, partendo dal metodo più veloce

1. Leggi la console. Riproduci il guasto con gli strumenti per sviluppatori aperti. Un errore come Uncaught TypeError ... some-plugin/build/index.js punta dritto al plugin responsabile. Questo singolo passaggio risolve la maggior parte dei casi e ti risparmia una bisezione alla cieca.

2. Escludi il browser. Fai un hard refresh (Cmd/Ctrl+Shift+R), poi prova una finestra in incognito con le estensioni disattivate. Ad blocker ed estensioni per la privacy a volte rimuovono script dell’area di amministrazione. Se in incognito funziona, il problema è un’estensione del browser o una cache obsoleta, non il tuo sito.

3. Controlla direttamente la REST API se hai visto il messaggio “risposta non valida JSON”. Visita https://iltuosito.com/wp-json/ nel browser. Dovresti ottenere un muro di JSON. Se invece ottieni HTML, un errore 500 o un redirect al login, è quello il tuo bug: un plugin sta rompendo la risposta REST, non l’editor in sé.

4. Biseziona i plugin. Disattivali tutti, verifica che l’editor si carichi, poi riattivali uno alla volta finché non si rompe di nuovo. Se sei completamente bloccato fuori da wp-admin, fallo via SFTP rinominando la cartella:

mv wp-content/plugins wp-content/plugins_off

WordPress disattiva tutto quando la cartella sparisce. Rinominala di nuovo com’era, poi sposta i plugin dentro e fuori uno per uno.

5. Prova il tema. Passa a Twenty Twenty-Four. Un tema che accoda JS rotto per l’editor o che genera errori PHP nel functions.php produce gli stessi sintomi.

6. Attiva il log e leggi l’errore vero. Soprattutto per i guasti REST/JSON, abilita il debug in wp-config.php:

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

L’errore fatale viene scritto in wp-content/debug.log con il file e il numero di riga esatti. Se quello stack trace è fitto — nomi di classi con namespace, catene di require, un fatale sepolto sotto dieci righe di traccia — incollalo nel nostro decodificatore del log errori di WordPress per vedere, in parole chiare, quale plugin e quale riga l’hanno effettivamente innescato. È la differenza tra “qualcosa è rotto” e “la riga 214 di questo specifico plugin è rotta”.

Se sospetti che la concatenazione degli script stia mascherando il vero colpevole, forza il caricamento separato di ogni script in modo che l’errore in console punti a un solo file:

define( 'SCRIPT_DEBUG', true );
define( 'CONCATENATE_SCRIPTS', false );

Cosa non fare

Non installare il plugin Classic Editor pensando di aver risolto. Non risolve nulla: nasconde l’editor a blocchi così smetti di vedere l’errore. Il JavaScript rotto o la risposta REST rotta sono ancora lì, e ti si ripresenteranno nel site editor, nei widget o alla prossima volta che aggiorni. Diagnostica prima; ripiega sul Classic solo se hai preso la decisione consapevole di smettere di usare i blocchi.

Non alzare il memory_limit di PHP per riflesso. È il fix copia-e-incolla preferito di internet, ma un editor bianco raramente è dovuto all’esaurimento della memoria. Un vero esaurimento genera un fatale specifico — “Allowed memory size of N bytes exhausted” — che vedrai in debug.log. Se quella riga non c’è, aggiungere memoria non cambia nulla.

Non reinstallare il core di WordPress. I file del core sono identici byte per byte in ogni installazione. Se il problema fosse il core, ogni sito WordPress al mondo avrebbe l’editor rotto in questo momento. La colpa è quasi sempre nei tuoi plugin o nel tema, e reinstallare il core rischia di sovrascrivere cose senza risolvere nulla.

Non svuotare né disattivare alla cieca il tuo plugin di cache come primo passo. La minificazione e la concatenazione aggressiva del JS possono rompere l’editor, quindi vale la pena testarlo, ma controlla la console prima di metterti a svuotare cache a casaccio. Tirare a indovinare è il modo in cui un fix da cinque minuti diventa un pomeriggio intero.

Ancora bloccato?

Se la console è pulita, la REST API restituisce JSON valido e una bisezione completa di plugin e tema lascia comunque l’editor morto, la risposta è quasi sempre lì che ti aspetta in debug.log. Abilita WP_DEBUG_LOG, riproduci il guasto una volta ed esegui il fatale risultante attraverso il decodificatore del log errori. Lo stack trace nomina il file: parti da lì.