Gutenberg sa zasekol: oprava blokového editora WordPressu

Ak ste niekedy videli, že sa editor blokov zasekol na hlásení „Načítava sa…“ alebo sa zobrazila správa „V editore sa vyskytla neočakávaná chyba“, pravdepodobne máte problém s REST API, administrátorskými skriptami alebo ukladaním do vyrovnávacej pamäte/zabezpečením. Vo WordPresse 6.9.4 (apríl 2026) sa Gutenberg ešte viac ako predtým spolieha na čisté administrátorské rozhranie: REST API, jednorazové čísla, verziované skripty a čisté odpovede JSON.

Problém

Typické správy, ktoré vidím v konzole prehliadača (alebo v používateľskom rozhraní), vyzerajú takto:

"The editor has encountered an unexpected error."
"Updating failed. The response is not a valid JSON response."
"Error: The REST API encountered an error."
"GET https://example.com/wp-json/wp/v2/types/post?context=edit 403 (Forbidden)"

Zobrazuje sa v administrátorskom paneli na Články → Pridať / Stránky → Upraviť, niekedy iba pri určitých typoch obsahu (CPT) a často hneď po:

• aktualizácia doplnku zabezpečenia/vyrovnávacej pamäte,
• zmena pravidla WAF/CDN (Cloudflare, Sucuri, ModSecurity),
• pridanie úryvku, ktorý „vyčistí“ HTML kód,
• migrácia (URL, HTTPS, reverzná proxy),
• alebo aktualizácia témy (Avada) / nástroja na tvorbu stránok (Elementor, Divi 5), ktorá pridáva administrátorské skripty.

Táto príručka je určená pre mierne pokročilých používateľov: viete, ako otvoriť konzolu, prečítať si protokol, nainštalovať MU-plugin a používať WP-CLI. Na konci budete schopní izolovať príčinu (REST, JS, vyrovnávacia pamäť, zabezpečenie, PHP) a použiť čistú opravu, kompatibilnú s WordPressom 6.9.4+ a PHP 8.1+.

Rýchle zhrnutie

• Začnite s konzolou : chyba visible (403 REST, neplatný JSON, JS súbor 404) určuje zvyšok.
• Okamžitý REST test : /wp-json/wp/v2/types/post?context=edit po prihlásení a potom porovnajte s účtom správcu.
• Zakážte rušenie : bezpečnostné/cache pluginy, úryvky kódu, optimalizácia JS/CSS, CDN a následne ich jeden po druhom reaktivovať.
• Povoliť čisté protokoly : WP_DEBUG_LOG + Monitor dotazov a vyhľadajte výrazy „REST“, „nonce“, „hlavičky už odoslané“ a „fatálne“.
• Neopravujte Gutenberga pomocou jQuery Väčšina zlyhaní pochádza z frontu alebo filtra, ktorý upravuje odpovede JSON.
• Ak ste na staviteľovi Divi 5/Elementor/Avada pridávajú administrátorské prvky; častý je konflikt optimalizácie alebo zabezpečenia.

Príznaky

Tu sú príznaky, ktoré vidím najčastejšie (od najbežnejších po naj„zložitejšie“).

• Biela obrazovka v editore s nekonečným spinnerom.
• Správa používateľského rozhrania „Vydavateľ narazil na neočakávanú chybu.“
• Chyba pri publikovaní „Aktualizácia zlyhala. Odpoveď nie je platná odpoveď JSON.“
• Konzola prehliadača (F12 → Konzola / Sieť):
  • 403/401 ďalej /wp-json/... (často WAF alebo bezpečnostné pravidlo),
  • 500 na REST trase (fatálne PHP na strane servera),
  • 404 v súbore wp-includes/js/dist/*.min.js (vyrovnávacia pamäť/CDN alebo neúplné nasadenie),
  • Chyby CORS alebo CSP (príliš prísne bezpečnostné hlavičky),
  • Unexpected token < in JSON (HTML vložený do odpovede JSON, zvyčajne do varovania PHP alebo stránky HTML 403).
• Funguje to lokálne, ale nie v produkcii CDN, agresívne ukladanie do vyrovnávacej pamäte, WAF alebo rozdiely v PHP/rozšíreniach.
• Funguje to pre administrátora, ale nie pre editora. : schopnosti, jednorazové čísla alebo plugin, ktorý filtruje podľa roly.
• Rozbije sa to iba na CPT : show_in_rest chýbajúca alebo vlastná REST trasa, ktorá je fatálna.

Rýchla diagnostická tabuľka

symptóm	Príčina pravdepodobná	overenie	Riešenie
„Neplatná odpoveď JSON“	HTML/upozornenie vložené do REST	Otvorte sieťovú odpoveď /wp-json/...	Zakázať plugin/úryvok kódu, korektné Upozornenia, pozri riešenie 1
403 dňa /wp-json/	WAF, bezpečnostné pravidlo, základné overenie	Test REST v režime súkromného prehliadania + protokoly WAF	Pridanie hlavičiek REST + na bielu listinu, pozri riešenie 1
Nekonečný spinner, chyby JS	Nefunkčný administrátorský front / optimalizácia JS	Konzola: „Nie je možné prečítať vlastnosti nedefinovaného“	Opraviť Zaradenie do frontu, vylúčenie aktív, pozri riešenie 2
404 dňa wp-includes/js/dist/	Nedokončené nasadenie / vyrovnávacia pamäť CDN	Otestujte vypnutím CDN a vymazaním vyrovnávacej pamäte	Vyčistenie a opätovné nasadenie, pozri riešenie 3
500 na ceste REST	Fatal PHP (plugin/téma)	WP_DEBUG_LOG + Monitor dotazov	Ak chcete opraviť závažné chyby, vráťte sa späť, pozrite si riešenie 1

Prečo sa to deje?

Jednoducho povedané: blokový editor je JavaScriptová aplikácia, ktorá neustále komunikuje s vašou webovou stránkou prostredníctvom REST API. Ak REST vráti niečo iné ako čistý JSON (alebo ak sa potrebné skripty nepodarí načítať), editor nemôže inicializovať svoj stav.

Tu je to, čo sa deje v zákulisí (technická verzia):

• Gutenberg načítava balíčky z wp-includes/js/dist/ a administratívne štýly.
• Načítava dáta prostredníctvom koncových bodov REST (typy, taxonómie, nastavenie, automatické ukladanie, zverejniť, Atď).
• Odosiela overené požiadavky s jednorazovými číslami (nonce). Ak plugin upraví hlavičky, blokuje trasy alebo ukladá do vyrovnávacej pamäte odpovede „upraviť kontext“, preruší sa.
• Upozornenie PHP, „upozornenie“ alebo dokonca medzera pred <?php môže stačiť na znečistenie odpovede JSON.

Pravdepodobné príčiny (od najčastejších po najzriedkavejšie):

1. Blokovanie REST zabezpečením/cache/CDN (403, výzva, základné overenie, pravidlo ModSecurity).
2. znečistená REST odpoveď varovaním PHP, var_dump()alebo plugin, ktorý vypíše HTML.
3. Optimalizácia JS/CSS ktorý kombinuje/minimizuje administračné (alebo „odkladá“ WordPress skripty).
4. Zle navrhnutý administrátorský front (chýbajúce závislosti, nevhodný hook, globálne načítavanie na všetkých stránkach).
5. Záhlavia CSP/zabezpečenia príliš prísne (bloky blob:, data:alebo očakávané skripty/štýly).
6. Nekonzistentnosť vyrovnávacej pamäte (servisný pracovník, vyrovnávacia pamäť prehliadača, vyrovnávacia pamäť objektov, CDN), ktorý poskytuje prvky z inej verzie.
7. Problém so serverom (oprávnenia k súborom, neúplné nasadenie, opcache, chýbajúce PHP rozšírenie).

Predpoklady pred začatím

• zabezpečiť súbory + databáza (alebo snapshot, ak používate spravovanú hostingovú službu). Netestujte „náhodne“ v produkčnom prostredí.
• Testovacie prostredie ideálne obdobie prípravy alebo aspoň obdobie údržby.
• verzia Odporúča sa WordPress 6.9.4 a PHP 8.1+. Prihlásiť sa Nástroje → Stav stránky.
• Užitočné pluginy :
  • Monitor dopytov (dotazy, chyby PHP, hooky, REST).
  • Kontrola stavu a riešenie problémov (režim riešenia problémov bez ovplyvnenia návštevníkov).
• Záznamy dočasne aktivovať WP_DEBUG_LOG (bez zobrazenia na front-ende).

Odporúčaná (dočasná) konfigurácia v wp-config.php :

<?php
// Active le debug sans afficher les erreurs à l'écran (évite de polluer des réponses JSON).
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );

// Log dans wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Optionnel : réduit les "notices" bruyantes de certains plugins (à ajuster selon votre besoin).
// error_reporting( E_ALL & ~E_NOTICE & ~E_DEPRECATED );

Bezpečnostné riziko neodchádzaj WP_DEBUG trvalo povolené na verejnej stránke. Záznamy môžu obsahovať cesty, požiadavky a dokonca aj citlivé informácie.

Riešenie 1: Rozhranie REST API je blokované (403/401/500) a Gutenberg sa už nedá spustiť.

Keď sa Gutenberg nenačíta, vždy začnem s jednoduchým REST požiadavkou. Pretože ak je REST pokazený, môžete opraviť všetky skripty na svete: editor zostane nestabilný.

Diagnostický

1. Otvorte editor ako správca a potom stlačte F12 → tabulátor Sieť.
2. Filtrovať zapnuté wp-json.
3. Identifikujte prvý chybový dotaz (často types, settings, posts).
4. Kliknite na dopyt → zobrazte odpoveď :
   • Ak vidíte HTML kód (chybová stránka, výzva, prihlásenie), našli ste ho.
   • Ak sa vo WordPresse zobrazí chybový súbor JSON, poznačte si ho code et message.

Rýchly test z príkazového riadka (ak máte WP-CLI + cookie/nonce, je to zložitejšie). Pre jednoduchý test ho spustite v prehliadači po prihlásení:

URL : https://votre-site.tld/wp-json/wp/v2/types/post?context=edit

Ak sa zobrazí chyba 403/401 alebo chyba HTML stránky, príčina je takmer vždy externá pre WordPress (WAF, bezpečnostný plugin, Basic Auth, reverzná proxy).

Bežný prípad: plugin blokuje REST pomocou príliš agresívneho filtra

Často som narazil na úryvky, ktoré z bezpečnostných dôvodov „zakazujú REST API“, ale zároveň narúšajú fungovanie editora (a niekedy aj Elementoru/Divi/Avady na strane administrátora).

PREDNÁ ČASŤ (rozbitá)

<?php
// Mauvaise idée : bloque l'API REST pour tout le monde, y compris l'admin.
// Résultat : Gutenberg ne peut plus charger.
add_filter( 'rest_authentication_errors', function( $result ) {
	return new WP_Error(
		'rest_disabled',
		'REST API désactivée',
		array( 'status' => 403 )
	);
} );

PO (opravené, cielené obmedzenie)

<?php
/**
 * Restriction REST plus sûre : ne bloque pas l'admin, et limite seulement certaines routes publiques.
 * À placer dans un plugin (ou MU-plugin), pas dans functions.php si vous changez souvent de thème.
 */
add_filter( 'rest_authentication_errors', function( $result ) {

	// Si une authentification a déjà échoué/réussi, respectez le résultat.
	if ( ! empty( $result ) ) {
		return $result;
	}

	// Autorisez toujours les utilisateurs connectés (Gutenberg en dépend).
	if ( is_user_logged_in() ) {
		return $result;
	}

	// Exemple : bloquer uniquement une route custom publique (à adapter).
	$request_uri = isset( $_SERVER['REQUEST_URI'] ) ? (string) $_SERVER['REQUEST_URI'] : '';

	if ( str_contains( $request_uri, '/wp-json/mon-namespace/v1/' ) ) {
		return new WP_Error(
			'rest_forbidden',
			'Accès REST interdit.',
			array( 'status' => 403 )
		);
	}

	return $result;
} );

Prečo to opravuje Gutenberg volá REST koncové body v kontexte edit ktoré vyžadujú pripojenú reláciu. Blokovanie REST „globálne“ je ekvivalentné odpojeniu interného API vydavateľa.

Bod ostražitosti Tento typ filtra musí byť presný. Blokovanie podľa „prítomnosti /wp-json/„je anti-vzor. Ak naozaj chcete znížiť expozíciu REST, robte to trasu po trase a otestujte administrátora.

Bežný prípad: „Neplatná odpoveď JSON“ z dôvodu varovania PHP

Keď REST odpoveď začína kódom HTML, Gutenberg často zobrazí „neplatnú JSON odpoveď“. Skutočnou príčinou je niekedy jednoduché PHP varovanie vypísané pred JSON kódom.

PREDNÁ ČASŤ (rozbitá)

<?php
// Exemple réaliste : un plugin/thème affiche un warning (variable non définie) et pollue la réponse REST.
add_action( 'init', function() {
	// Mauvais : echo en init, peut s'exécuter pendant une requête REST.
	if ( isset( $_GET['debug'] ) ) {
		echo "DEBUG"; // Pollue la sortie JSON.
	}
} );

PO (opravené)

<?php
// Ne jamais "echo" dans le cycle WordPress global.
// Utilisez error_log() et limitez à WP_DEBUG.
add_action( 'init', function() {
	if ( defined( 'WP_DEBUG' ) && WP_DEBUG && isset( $_GET['debug'] ) ) {
		error_log( 'Debug init déclenché' );
	}
} );

Prečo to opravuje REST API musí vrátiť striktný JSON. Akýkoľvek výstupný znak (upozornenie, BOM, echo) preruší parsovanie JSON na strane prehliadača.

Bežný prípad: Blokovanie WAF/CDN (403, výzva, základné overenie)

Ak je odpoveďou 403 HTML stránka s textom „Prístup zamietnutý“ alebo výzva, WordPress nie je zodpovedný.

• Dočasne vypnite WAF/CDN (alebo prepnite do „vývojárskeho režimu“).
• Explicitne povoliť /wp-json/ et /wp-admin/admin-ajax.php.
• Ak máte v režime testovania povolené základné overenie, Gutenberg môže zlyhať v závislosti od konfigurácie prehliadača. V takom prípade povoľte IP adresu správcu alebo dočasne vypnite základné overenie počas úprav.

Pre pochopenie REST zmluvy na strane WordPressu je oficiálna dokumentácia tu: Príručka REST API.

Riešenie 2: Poškodené skripty editora (zaradenie do frontu, závislosti, poradie načítania)

Druhý klasický scenár: téma alebo plugin načíta skript v administrátorskom paneli, ale:

• na nesprávnom háku,
• bez závislostí,
• alebo prepísaním knižnice (React, lodash), ktorú WordPress už poskytuje.

Výsledok: Chyby JS typu wp is not defined, Cannot read properties of undefined, alebo tichý náraz.

Diagnostický

1. F12 → Konzola: všimnite si premiéra chyba (nie 15.). Príčinou je často prvá.
2. F12 → Sieť: vyhľadať JS súbor s chybou 404/blokované.
3. Dočasne deaktivujte optimalizačné pluginy (minifikácia/kombinácia/odloženie), ktoré ovplyvňujú administrátorský panel.

Bežný prípad: globálny prieskum o admin_enqueue_scripts bez zacielenia na obrazovku

Často som všade videl načítaný skript „admin“, ktorý predpokladá existenciu wp.data (Gutenberg) aj na obrazovkách, ktoré ho nenačítajú. Alebo naopak: prepíše globálne premenné.

PREDNÁ ČASŤ (rozbitá)

<?php
// Mauvais : charge un script partout dans l'admin, sans dépendances, et trop tôt.
// Sur l'écran de l'éditeur, ça peut entrer en conflit.
add_action( 'admin_enqueue_scripts', function() {
	wp_enqueue_script(
		'mon-admin',
		get_stylesheet_directory_uri() . '/assets/admin.js',
		array(), // Oublie des dépendances éventuelles.
		'1.0',
		true
	);
} );

PO (opravené: zacielenie + závislosti + verziovanie)

<?php
/**
 * Charge un script admin uniquement sur l'éditeur de blocs, avec des dépendances correctes.
 * Compatible WP 6.9.4+.
 */
add_action( 'admin_enqueue_scripts', function( $hook_suffix ) {

	// Cible les écrans post.php (édition) et post-new.php (création).
	if ( ! in_array( $hook_suffix, array( 'post.php', 'post-new.php' ), true ) ) {
		return;
	}

	$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;
	if ( ! $screen ) {
		return;
	}

	// Optionnel : ne chargez que pour certains post types.
	$allowed_post_types = array( 'post', 'page' );
	if ( empty( $screen->post_type ) || ! in_array( $screen->post_type, $allowed_post_types, true ) ) {
		return;
	}

	$src  = get_stylesheet_directory_uri() . '/assets/admin-editor.js';
	$path = get_stylesheet_directory() . '/assets/admin-editor.js';

	wp_enqueue_script(
		'mon-admin-editor',
		$src,
		array( 'wp-data', 'wp-edit-post', 'wp-element' ), // Dépendances Gutenberg.
		file_exists( $path ) ? filemtime( $path ) : '1.0.0',
		true
	);
} );

Prečo to opravuje Vyhnete sa tak preplneniu celého administrátorského panela, načítate iba tam, kde je prítomný Gutenberg, a deklarujete stabilné závislosti. Verzionovanie podľa filemtime() Taktiež sa tým zabráni vzniku „fiktívnych“ vyrovnávacích pamätí po nasadení.

Bežný prípad: plugin manuálne načíta React/ReactDOM

Ak plugin obsahuje vlastnú verziu Reactu (alebo ho načíta cez CDN) v administrátorskom paneli, môžete naraziť na chyby, ktoré je ťažké diagnostikovať, najmä po aktualizácii WordPressu. WordPress už poskytuje potrebné balíčky pre editor.

PREDNÁ ČASŤ (rozbitá)

<?php
// Anti-pattern : charger React via CDN dans l'admin.
// Peut casser Gutenberg (deux React différents).
add_action( 'admin_enqueue_scripts', function() {
	wp_enqueue_script( 'react', 'https://unpkg.com/react@18/umd/react.production.min.js', array(), null, true );
	wp_enqueue_script( 'react-dom', 'https://unpkg.com/react-dom@18/umd/react-dom.production.min.js', array( 'react' ), null, true );
} );

PO (opravené: použite balíčky WordPressu)

<?php
// Utilisez les packages WordPress (wp-element) au lieu de React embarqué.
add_action( 'admin_enqueue_scripts', function( $hook_suffix ) {
	if ( ! in_array( $hook_suffix, array( 'post.php', 'post-new.php' ), true ) ) {
		return;
	}

	wp_enqueue_script(
		'mon-ui',
		plugin_dir_url( __FILE__ ) . 'assets/mon-ui.js',
		array( 'wp-element', 'wp-components', 'wp-i18n' ),
		'1.0.0',
		true
	);
} );

Užitočná dokumentácia: balík wp-element et Príručka editora blokov.

Kompatibilita s Divi 5 / Elementor / Avada

• Divi 5 Ak povolíte možnosti výkonu, ktoré „optimalizujú“ administrátorské rozhranie, otestujte následne Gutenberg. Divi niekedy načíta editory zdrojov pre svoje moduly; vylúčte ich. /wp-admin/ agresívne optimalizácie.
• Elementor Aj keď má Elementor vlastný editor, integruje sa s administračným panelom WordPressu. Optimalizačný doplnok, ktorý kombinuje administračné skripty, môže narušiť funkčnosť Gutenbergu a obrazovky Elementoru.
• Avada Fusion Builder a Avada Live načítavajú náročné skripty. Ak máte proces vyrovnávacej pamäte/minifikácie, ktorý ovplyvňuje administrátorskú oblasť, Avada je často prvý, kto problém odhalí.

Riešenie 3: Ukladanie do vyrovnávacej pamäte, zabezpečenie a CSP (Content-Security-Policy), ktoré narúšajú administrátorskú prácu

Keď vidím, že Gutenberg funguje „iba polovične“ alebo až po úplnom obnovení, mám podozrenie na problém s vyrovnávacou pamäťou. Keď vidím chyby „Odmietnuté načítanie… pretože porušuje CSP“, mám podozrenie na zle nakonfigurované bezpečnostné hlavičky.

Bežný prípad: optimalizácia, ktorá minimalizuje/zreťazuje administrátorské súbory

Mnoho optimalizačných pluginov má možnosť „Optimalizovať aj administračnú oblasť“. Na WordPresse 6.9.4 je to často zlý nápad: administračné rozhranie sa rýchlo mení, balíčky sú už optimalizované a riziko narušenia závislostí je reálne.

Konkrétna akcia:

• Zakázať optimalizáciu JS/CSS /wp-admin/.
• Vylúčte minimálne:
  • /wp-includes/js/dist/
  • /wp-admin/js/
  • load-scripts.php et load-styles.php (ak sa používa)
• Vymazanie: vyrovnávacia pamäť pluginov + vyrovnávacia pamäť servera + CDN + prehliadač.

Bežný prípad: Príliš prísny socioekonomický status

„Vysoko zabezpečený“ CSP môže blokovať mechanizmy používané vydavateľom (v závislosti od pluginov, médií, prvkov iframe atď.). Chyby sa zobrazujú v konzole, nie vo WordPresse.

Príklad chyby v konzole:

Refused to load the script 'blob:https://example.com/...' because it violates the following Content Security Policy directive...

Ak spravujete CSP cez PHP (bezpečnostný plugin, vlastné hlavičky), otestujte to uvoľnením obmedzení iba pre administrátorský panel. Tu je príklad. minimum (upraviť a overiť podľa vašej bezpečnostnej politiky):

<?php
/**
 * Exemple : définir des headers CSP uniquement dans l'admin.
 * Attention : une CSP doit être pensée globalement. Ne copiez pas ceci sans comprendre votre surface d'attaque.
 */
add_action( 'send_headers', function() {

	if ( ! is_admin() ) {
		return;
	}

	// Exemple volontairement simple. Ajustez selon vos besoins.
	// Objectif : éviter de casser des scripts/styles nécessaires à l'éditeur.
	header( "Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self' https:; frame-src 'self';" );
}, 20 );

Prečo to opravuje Gutenberg a niektoré administrátorské komponenty môžu používať URL adresy. blob: / data: (v závislosti od funkcií a rozšírení). Príliš obmedzujúci CSP blokuje načítavanie/vyhodnocovanie a JS aplikácia sa nespustí.

Bezpečnostné riziko : 'unsafe-inline' et 'unsafe-eval' Toto zvyšuje riziko XSS. V ideálnom prípade to nechcete. Ale v skutočnosti mnoho WP stackov (vrátane pluginov) nie je pripravených na dokonalý „striktne dynamický“ CSP. Implementujte progresívny CSP a použite režim Iba prehľad iterovať.

Bežný prípad: prvky zo staršej verzie poskytované cez CDN/opcache

Po aktualizácii WordPressu som už videl niekoľko wp-includes/js/dist/* poskytovanie súborov z predchádzajúcej verzie prostredníctvom CDN. Gutenberg potom načíta kombináciu nekompatibilných verzií.

Kontrolný zoznam:

• Vymažte CDN (a nielen vyrovnávaciu pamäť pluginov).
• Ak máte prístup, vymažte vyrovnávaciu pamäť PHP (alebo reštartujte PHP-FPM).
• Overte, či sa nasadenie úspešne nahralo. všetko Súbory WordPressu (najmä cez manuálny SFTP).

Kontroly po korekcii

• Otvorte existujúci článok a vytvorte nový: obe obrazovky by mali fungovať.
• Otestujte s účtom admin potom účet vydavateľ (Možnosti REST sa líšia).
• Konzola: nula Červená chyba pri úvodnom načítaní. Môžu existovať nejaké upozornenia, ale žiadna blokujúca chyba.
• Sieť: požiadavky /wp-json/ musí byť vo formáte 200 a odpoveď musí byť vo formáte JSON.
• Rýchly test publikovania: koncept → publikovať → aktualizovať.

Ak používate Elementor/Divi/Avada, otvorte aj ich editačné obrazovky: „admin“ patch by mal vylepšiť celý systém, nielen Gutenberg.

Ak to stále nefunguje

Postup používam, keď problém pretrváva (v tomto poradí, pretože sa tým zabráni začarovanému kruhu).

1) Režim riešenia problémov bez ovplyvnenia návštevníkov

• umožniť Health Check a použite režim riešenia problémov.
• V tomto režime vypnite všetky pluginy a ponechajte tému aktívnu.
• Skús Gutenberga.

Ak to funguje, znova aktivujte pluginy jeden po druhom, kým nenájdete vinníka (často zabezpečenie, vyrovnávacia pamäť, optimalizácia alebo zle naprogramovaný plugin pre vlastné polia).

2) Skontrolujte protokoly PHP a chyby REST

• otvorené wp-content/debug.log hneď po neúspešnom načítaní.
• Hľadať: Fatal error, headers already sent, Deprecated (niektoré zastarané verzie môžu po zobrazení znehodnotiť výstup), REST.

Ak chcete porozumieť chybám „neplatný JSON“, oficiálna dokumentácia ladenia je tu: Ladenie vo WordPress.

3) Monitor dotazov: kontrola chýb a požiadaviek AJAX/REST

Query Monitor zobrazuje chyby PHP, prekážky a niekedy aj HTTP volania. Pri riešení problémov s Gutenbergom ho používam hlavne na:

• identifikovať varovanie, ktoré sa spustí pri požiadavke REST,
• Identifikujte zodpovedný doplnok pomocou stopy zásobníka.
• Skontrolujte, či administrátor nenačítava nejaké neočakávané skripty.

4) Skontrolujte stav stránky a limity servera

• PHP pamäť Gutenberg, tvorcovia a rozsiahle pluginy môžu spôsobovať problémy. Nedostatok pamäte môže viesť k občasným pádom.
• Limity : max_input_vars Príliš nízka hodnota môže mať vplyv na niektoré obrazovky (menej časté na čistom Gutenbergu, viac na ťažkých metaboxoch).
• Oprávnenie Ak základné súbory WP nie sú čitateľné, zobrazí sa vám chyba 404/500 v súboroch.

5) Obnovenie trvalých odkazov (zriedkavé, ale rýchle)

Keď REST vráti chybu 404, aj keď súbor existuje, po migrácii som zaznamenal nekonzistentné pravidlá prepisovania.

1. Nastavenia → Trvalé odkazy → Uložiť (bez zmien).

6) Skontrolujte konflikt úryvkov kódu

Pluginy úryvkov kódu (alebo functions.php) sú hlavnou príčinou, pretože jednoduchá syntaktická chyba všetko pokazí.

• Hľadajte chybu „chýbajúca bodkočiarka“ alebo chybu v zátvorkách.
• Skontrolujte, či sa spúšťa úryvok kódu init / wp_loaded a urobil echo / var_dump.

7) WP-CLI: Kontrola integrity a verzií

Na stránke, kde mám podozrenie na neúplné nasadenie, je WP-CLI veľmi efektívne:

# Vérifie l'intégrité des fichiers du core WordPress
wp core verify-checksums

# Liste plugins et mises à jour en attente
wp plugin list
wp plugin update --all

# Vérifie la version PHP (vue par WP-CLI)
php -v

Dokumentácia WP-CLI: Príkazy WP-CLI.

Časté úskalia a chyby

symptóm	Príčina pravdepodobná	Odporúčané riešenie
„Neplatná odpoveď JSON“ po pridaní úryvku kódu	echo/var_dump alebo upozornenie PHP počas REST	Odstráňte výstup, použite error_log()Správne upozornenia (Riešenie 1)
Gutenberg sa načítava iba v určitých prehliadačoch.	Vyrovnávacia pamäť prehliadača/servisný pracovník alebo rozšírenie	Otestujte si súkromné ​​prehliadanie, vypnite rozšírenia, vymažte vyrovnávaciu pamäť (riešenie 3)
Chyba JS „wp nie je definovaný“	Skript sa načítal príliš skoro alebo na nesprávnej obrazovke	Cieľ post.php/post-new.php + závislosti (Riešenie 2)
403 dňa /wp-json/ iba vo výrobe	WAF/CDN, pravidlo ModSecurity, základné overenie	Pridanie na bielu listinu REST/admin-ajax, protokoly WAF, obídenie (riešenie 1)
Po vypnutí vyrovnávacej pamäte to funguje, potom to znova prestane fungovať.	Plugin pre reaktívnu optimalizáciu „minify admin“	Vylúčiť /wp-admin/ a balíky WP (riešenie 3)
Chyba po aktualizácii WP, súbory JS zobrazujú chybu 404	Nedokončené nasadenie / CDN poskytuje starú verziu	Čistenie CDN + wp core verify-checksums (Riešenie 3)
Kód je „na správnom mieste“, ale nefunguje.	Skopírované do nesprávneho súboru (plugin verzus podradená téma) alebo nevhodný hook	Pridať do MU-pluginu, skontrolovať hook a prioritu
Funguje to iba pre rolu Editor.	Možnosti REST/nonce, plugin pre role	Otestujte REST trasy s touto rolou, správne funkcie

Chyby, ktoré často vidím u mierne pokročilých používateľov:

• Otestovať priamo v produkcii bez zálohy a potom urgentne „opraviť“.
• Pridajte úryvok zo starého tutoriálu (pred verziou 6.x), ktorý blokuje REST „z bezpečnostných dôvodov“.
• Zabudnutie vymazať vyrovnávaciu pamäť CDN po aktualizácii WordPressu.
• Použitie príliš globálneho hooku (napr. init) na tlač HTML alebo načítanie JS.
• Zmenšite/zreťazte administrátorský súbor „aby ste ušetrili 0,2 s“ a stratili editor.

Variant / alternatíva

Metóda bez kódu: izolácia pomocou kontroly stavu + kontrolované vrátenie zmien

• Kontrola stavu → režim riešenia problémov → deaktivácia doplnkov podľa kategórie (zabezpečenie/ukladanie do vyrovnávacej pamäte/optimalizácia).
• Ak sa zistí príčina, aktualizujte ju alebo vymeňte.
• Ak je chyba spôsobená nedávnou aktualizáciou, vykonajte dočasné vrátenie zmien (plugin) a potom otvorte tiket u vydavateľa.

Pokročilejšia metóda: „ochrana“ MU-pluginu pre zaznamenávanie REST chýb

Keď je stránka zložitá (Avada + Elementor + zabezpečenie + vyrovnávacia pamäť), niekedy nainštalujem dočasný MU-plugin na zaznamenávanie REST chýb bez prerušenia produkcie.

<?php
/**
 * Plugin Name: MU - Debug REST pour éditeur de blocs
 * Description: Journalise les erreurs REST (temporaire) pour diagnostiquer Gutenberg.
 * Author: Votre équipe
 * Version: 1.0.0
 *
 * À placer dans wp-content/mu-plugins/mu-debug-rest.php
 */

add_filter( 'rest_request_after_callbacks', function( $response, $handler, $request ) {

	// Ne loguez que si WP_DEBUG est actif pour éviter du bruit en prod.
	if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
		return $response;
	}

	if ( is_wp_error( $response ) ) {
		error_log( '[REST][WP_Error] route=' . $request->get_route() . ' code=' . $response->get_error_code() . ' message=' . $response->get_error_message() );
		return $response;
	}

	if ( $response instanceof WP_REST_Response ) {
		$status = $response->get_status();
		if ( $status >= 400 ) {
			error_log( '[REST][HTTP ' . $status . '] route=' . $request->get_route() );
		}
	}

	return $response;
}, 10, 3 );

Toto zabezpečenie pomáha korelovať poškodenú obrazovku Gutenbergu s presnou REST trasou.

Vyhnite sa tomuto problému v budúcnosti

• Neblokovať REST globálneAk posilňujete zabezpečenie, urobte tak podľa trás, rolí a kontextov. Po každej zmene otestujte administrátora.
• Neoptimalizujte administráciu (zmenšiť/zlúčiť/odložiť) okrem veľmi kontrolovaných prípadov. Zisky sú minimálne, riziká obrovské.
• Správne načítajte administrátorské skripty :
  • zacielenie na obrazovku ($hook_suffix + get_current_screen()),
  • závislosti wp-* vyhlásil,
  • spoľahlivé verzovanie (filemtime v jednoduchom prostredí).
• Monitorovanie upozornení PHP V PHP 8.1+ niektoré vzory spúšťajú viac upozornení/zastaraní. Zobrazené upozornenie môže narušiť JSON.
• Proces aktualizácie : staging → vymazanie vyrovnávacích pamätí → produkcia. A po aktualizácii WordPressu systematické vymazanie CDN.
• Bezpečnostné hlavičky : nasadiť CSP v Iba prehľad Najprv to postupne doťahujte. Inak vám ďalší plugin, ktorý pridá iframe alebo blob, „zlomí administráciu“.

Užitočné referencie PHP: Konfigurácia spracovania chýb PHP.

zdroje

• Príručka REST API (WordPress.org)
• Príručka editora blokov
• Ladenie vo WordPress
• Kontrola stavu a riešenie problémov (plugin)
• Monitor dotazov (plugin)
• WordPress Core Trac (tikety a história)
• Repozitár GitHub Gutenberg (problémy)
• Príkazy WP-CLI

často kladené otázky

Prečo Gutenberg zobrazuje „Odpoveď nie je platná odpoveď JSON“?

Pretože REST požiadavka očakáva JSON, ale dostane niečo iné (chyba HTML 403/500, upozornenie PHP, nechcený výstup). Otvorte odpoveď na karte Sieť: príčinu často uvidíte okamžite.

Je vypnutie rozhrania REST API „z bezpečnostných dôvodov“ dobrým postupom?

Nie, nie globálne. WordPress (a Gutenberg) ho používa interne. Ak ho chcete posilniť, urobte tak postupne a pri zachovaní funkčnosti administračného panela. Testujte systematicky. /wp-json/wp/v2/types/post?context=edit pripojený.

Prečo to funguje pre administrátora, ale nie pre editora?

Možnosti sa líšia a niektoré pluginy pre roly/zabezpečenie filtrujú REST na základe roly. Otestujte s príslušným účtom a skontrolujte chyby 403 na trasách REST v kontexte. edit.

Môže doplnok pre vyrovnávaciu pamäť narušiť Gutenberg?

Áno, najmä ak ukladá do vyrovnávacej pamäte overené koncové body REST alebo ak optimalizuje/minimalizuje administrátorské skripty. Vylúčiť /wp-admin/ et /wp-json/ agresívne pravidlá ukladania do vyrovnávacej pamäte.

Čo mám robiť, ak sa na trase REST zobrazí iba chyba 500?

Toto je takmer vždy fatálne volanie PHP spustené počas tejto požiadavky. Povoliť WP_DEBUG_LOGreprodukovať, potom sledovať debug.logMonitor dopytov pomáha identifikovať zodpovedný doplnok/tému.

Sú Divi 5 / Elementor / Avada kompatibilné s Gutenbergom?

Áno, ale pridávajú skripty a možnosti výkonu. Konflikty vznikajú najmä z optimalizácií administrátora, minifikácie alebo príliš prísnych bezpečnostných pravidiel. Ak Gutenberg prestane fungovať, otestujte aj editor builderov: príčina je často spoločná.

Pomohlo by „opätovné uloženie trvalých odkazov“?

Niekedy, ak REST po migrácii alebo zmene servera vráti chybu 404, nie je to prvá vec, ktorú treba urobiť, ale je to rýchle a bezrizikové.

Môžem „opraviť Gutenberg“ opätovným načítaním jQuery alebo pridaním vlastného JS?

Toto je zvyčajne len náplasťové riešenie, ktoré maskuje skutočný problém (nefunkčný REST server, konfliktné skripty). Opravte príčinu: blokovanie REST servera, chybné zaradenie do frontu, problémy s vyrovnávacou pamäťou/CDN alebo fatálne PHP.

Na ktoré súbory sa mám pozrieť, keď súbory Gutenbergu vracajú chybu 404?

Pozrite sa na URL adresy wp-includes/js/dist/ et wp-includes/css/dist/Chyba 404 môže naznačovať neúplné nasadenie alebo sieť CDN, ktorá poskytuje staršiu verziu. wp core verify-checksums veľa pomáha.

Vidím hlásenie „Odmietnuté načítanie… porušuje zásady zabezpečenia obsahu“. Čo mám robiť?

Uvoľnite CSP pre administrátora, ideálne do Iba prehľad Najprv si prečítajte pokyny. script-src, style-src, connect-srca autorizácia blob:/data: Ak je to potrebné. Robte to postupne, aby ste obmedzili riziko XSS.