Гутенберг заседна: поправете блоковия редактор на WordPress

Ако някога сте виждали блоковия редактор да се забива на „Зареждане…“ или да показва „Редакторът срещна неочаквана грешка“, вероятно имате проблем с вашия REST API, администраторски скриптове или кеширане/сигурност. В WordPress 6.9.4 (април 2026 г.), Gutenberg разчита още повече от преди на изчистен администраторски интерфейс: REST API, nonce, версирани скриптове и изчистени JSON отговори.

Проблемът

Типичните съобщения, които виждам в конзолата на браузъра (или в потребителския интерфейс), изглеждат така:

"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)"

Появява се в администраторския панел, на Статии → Добавяне / Страници → Редактиране, понякога само за определени видове съдържание (CPT) и често веднага след:

актуализация на плъгина за сигурност/кеш,
промяна в правилото за WAF/CDN (Cloudflare, Sucuri, ModSecurity),
добавяне на фрагмент, който „почиства“ HTML кода,
миграция (URL, HTTPS, обратен прокси),
или актуализация на тема (Avada) / конструктор на страници (Elementor, Divi 5), която добавя администраторски скриптове.

Това ръководство е за средно напреднали потребители: знаете как да отворите конзолата, да прочетете лог, да инсталирате MU-плъгин и да използвате WP-CLI. До края ще можете да изолирате причината (REST, JS, кеш, сигурност, PHP) и да приложите чиста корекция, съвместима с WordPress 6.9.4+ и PHP 8.1+.

Бързо обобщение

Започнете с конзолата : грешката видимият (403 REST, невалиден JSON, JS файл 404) диктува останалото.
Незабавен REST тест : /wp-json/wp/v2/types/post?context=edit докато сте влезли в системата, след което сравнете с администраторски акаунт.
Деактивирайте смущенията : плъгини за сигурност/кеш, фрагменти, JS/CSS оптимизация, CDN, след което ги активирайте отново един по един.
Активиране на чисти регистрационни файлове : WP_DEBUG_LOG + Query Monitor и потърсете „REST“, „nonce“, „headers already sent“ и „fatal“.
Не „поправяйте“ Гутенберг с jQuery Повечето от неуспехите идват от опашка или филтър, който променя JSON отговорите.
Ако сте на строител Divi 5/Elementor/Avada добавят администраторски ресурси; често се наблюдава конфликт с оптимизацията или сигурността.

Симптомите

Ето са симптомите, които виждам най-често (от най-често срещаните до най-„трудните“).

Бял екран в редактора с безкраен въртящ се механизъм.
Съобщение от потребителския интерфейс „Издателят се сблъска с неочаквана грешка.“
Грешка при публикуване „Актуализацията е неуспешна. Отговорът не е валиден JSON отговор.“
Конзола на браузъра (F12 → Конзола / Мрежа):
- 403/401 на /wp-json/... (често WAF или правило за сигурност),
- 500 по REST маршрут (фатален PHP от страна на сървъра),
- 404 във файл wp-includes/js/dist/*.min.js (кеш/CDN или непълно внедряване),
- Грешки в CORS или CSP (прекалено строги заглавки за сигурност),
- Unexpected token < in JSON (HTML, инжектиран в JSON отговор, обикновено PHP предупреждение или HTML 403 страница).
Работи локално, но не и в продукцията CDN, агресивно кеширане, WAF или разлики в PHP/разширения.
Работи за администратор, но не и за редактор. : възможности, еднократни стойности или плъгин, който филтрира според ролята.
Чупи се само на CPT : show_in_rest липсващ или персонализиран REST маршрут, който е фатален.

Бърза диагностична диаграма

симптом	Вероятна причина	проверка	Решение
„Невалиден JSON отговор“	HTML/предупреждение, инжектирано в REST	Отворете мрежовия отговор на `/wp-json/...`	Деактивиране на плъгина/фрагмента, corriger Предупреждения, вижте Решение 1
403 на `/wp-json/`	WAF, правило за сигурност, основно удостоверяване	Тестване на REST в режим на частно сърфиране + WAF логове	Белият списък с REST + заглавки, вижте Решение 1
Безкраен въртящ се механизъм, JS грешки	Неработеща административна опашка / JS оптимизация	Конзола: „Не могат да се прочетат свойствата на неопределено“	Поправям Поставяне на опашка, изключване на активи, вижте Решение 2
404 на `wp-includes/js/dist/`	Незавършено внедряване / CDN кеш	Тествайте, като деактивирате CDN и изчистите кеша	Прочистване и преразпределение, вижте Решение 3
500 на REST път	Фатален PHP (плъгин/тема)	WP_DEBUG_LOG + Монитор на заявки	За да коригирате фатални грешки, отменете старта, вижте Решение 1

Защо се случва това?

Казано по-просто: блоковият редактор е JavaScript приложение, което постоянно комуникира с вашия уебсайт чрез REST API. Ако REST върне нещо различно от чист JSON (или ако необходимите скриптове не се заредят), редакторът не може да инициализира състоянието си.

Ето какво се случва зад кулисите (техническа версия):

Гутенберг зарежда пакети от wp-includes/js/dist/ и администраторски стилове.
Извлича данни чрез REST крайни точки (типове, таксономии, настройки, автоматични запазвания, пускатИ т.н.).
Изпраща удостоверени заявки с еднократни стойности (nonce). Ако плъгин променя заглавките, блокира маршрути или кешира отговори за „редактиране на контекст“, той престава да функционира.
PHP предупреждение, „известие“ или дори интервал преди <?php може да бъде достатъчно, за да замърси JSON отговор.

Вероятни причини (от най-честите към най-редките):

Блокиране на REST от сигурност/кеш/CDN (403, предизвикателство, Basic Authentication, правило на ModSecurity).
замърсен REST отговор чрез PHP предупреждение, a var_dump()или плъгин, който отпечатва HTML.
JS/CSS оптимизация което комбинира/минимизира администраторските (или „отлага“ WordPress скриптове).
Лошо проектирана административна опашка (липсващи зависимости, неподходяща кука, глобално зареждане на всички страници).
CSP/заглавки за сигурност твърде строг (блокове blob:, data:или очакваните скриптове/стилове).
Несъответствие в кеша (сервизен работник, кеш на браузъра, кеш на обекти, CDN), който обслужва ресурси от друга версия.
Проблем със сървъра (права за достъп до файлове, непълно внедряване, opcache, липсващо PHP разширение).

Предварителни изисквания преди започване

защита файлове + база данни (или моментна снимка, ако сте на управлявана хостинг услуга). Не тествайте „на случаен принцип“ в продукция.
Тестова среда в идеалния случай, поетапно или поне период на поддръжка.
Версии Препоръчват се WordPress 6.9.4 и PHP 8.1+. Регистрирайте се. Инструменти → Състояние на сайта.
Полезни плъгини :
- Монитор на заявките (заявки, PHP грешки, куки, REST).
- Проверка на състоянието и отстраняване на неизправности (режим на отстраняване на неизправности без да се засягат посетителите).
Дневник временно активиране WP_DEBUG_LOG (без показване на предния край).

Препоръчителна (временна) конфигурация в 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 );

Риск за сигурността не си тръгвай WP_DEBUG постоянно активирано на публичен сайт. Регистрационните файлове могат да съдържат пътища, заявки и дори чувствителна информация.

Решение 1: REST API е блокиран (403/401/500) и Gutenberg вече не може да стартира

Когато Гутенберг не успее да се зареди, винаги започвам с проста REST заявка. Защото, ако REST е повреден, можете да поправите всички скриптове на света: редакторът ще остане нестабилен.

Диагностичен

Отворете редактора като администратор, след което натиснете F12 → Tab Мрежа.
Филтриране по wp-json.
Идентифицирайте първата заявка за грешка (често types, settings, posts).
Кликнете върху заявката → вижте отговор :
- Ако видите HTML (страница за грешка, предизвикателство, вход), значи сте го намерили.
- Ако видите JSON за грешка в WordPress, запишете си го code et message.

Бърз тест от команден ред (ако имате WP-CLI + cookie/nonce, е по-сложно). За прост тест, стартирайте го в браузъра, докато сте влезли в системата:

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

Ако получите грешка 403/401 или грешка в HTML страница, причината почти винаги е външна за WordPress (WAF, плъгин за сигурност, Basic Auth, обратен прокси).

Често срещан случай: плъгин блокира REST чрез прекалено агресивен филтър

Често съм попадал на фрагменти, които „деактивират REST API“ от съображения за сигурност, но те нарушават работата на редактора (а понякога и на Elementor/Divi/Avada от администраторската страна).

ПРЕДНА (счупена)

<?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 )
	);
} );

СЛЕД (коригирано, целенасочено ограничение)

<?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;
} );

Защо се коригира Гутенберг извиква REST крайни точки в контекст edit които изискват свързана сесия. Блокирането на REST „глобално“ е еквивалентно на прекъсване на връзката с вътрешния API на издателя.

Точка на бдителност Този тип филтър трябва да бъде прецизен. Блокира се чрез „наличие на /wp-json/" е анти-шаблон. Ако наистина искате да намалите REST експозицията, направете го маршрут по маршрут и тествайте администраторската версия.

Често срещан случай: „Невалиден JSON отговор“ поради PHP предупреждение

Когато REST отговорът започва с HTML, Gutenberg често показва „невалиден JSON отговор“. Истинската причина понякога е просто PHP предупреждение, отпечатано преди JSON.

ПРЕДНА (счупена)

<?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.
	}
} );

СЛЕД (коригирано)

<?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é' );
	}
} );

Защо се коригира REST API трябва да връща стриктен JSON. Всеки изходен символ (предупреждение, BOM, ехо) нарушава парсинга на JSON от страна на браузъра.

Често срещан случай: Блокиране на WAF/CDN (403, предизвикателство, Basic Authentication)

Ако отговорът 403 е HTML страница „Достъпът е отказан“ или предизвикателство, WordPress не носи отговорност.

Временно деактивирайте WAF/CDN (или превключете в „режим за разработчици“).
Изрично разрешаване /wp-json/ et /wp-admin/admin-ajax.php.
Ако сте активирали Basic Auth в режим на тестване, Gutenberg може да се провали в зависимост от конфигурацията на браузъра ви. В този случай, позволете IP адреса на администратора или временно деактивирайте Basic Auth, докато редактирате.

За да разберете REST договора от страна на WordPress, официалната документация е тук: Наръчник за REST API.

Решение 2: Неработещи скриптове на редактора (подреждане в опашка, зависимости, ред на зареждане)

Вторият класически сценарий: тема или плъгин зарежда скрипт в администраторския панел, но:

на грешната кука,
без зависимости,
или чрез презаписване на библиотека (React, lodash), която WordPress вече предоставя.

Резултат: JS грешки от типа wp is not defined, Cannot read properties of undefined, или безшумен срив.

Диагностичен

F12 → Конзола: обърнете внимание на премиера грешка (не 15-та). Първата често е причината.
F12 → Мрежа: търсене на JS файл с грешка 404/блокирано.
Временно деактивирайте плъгините за оптимизация (минимизиране/комбиниране/отлагане), които влияят на администраторския панел.

Често срещан случай: глобално проучване на `admin_enqueue_scripts` без да се насочвате към екрана

Често съм виждал навсякъде зареден скрипт „администратор“, който предполага съществуването на wp.data (Гутенберг) дори на екрани, които не го зареждат. Или обратното: презаписва глобални променливи.

ПРЕДНА (счупена)

<?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
	);
} );

СЛЕД (коригирано: насочване + зависимости + версии)

<?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
	);
} );

Защо се коригира Избягвате претрупването на целия администраторски панел, зареждате само там, където е наличен Gutenberg, и декларирате стабилни зависимости. Версиониране от filemtime() Освен това се избягват „фантомни“ кешове след внедряване.

Често срещан случай: плъгин ръчно зарежда React/ReactDOM

Ако даден плъгин включва собствена версия на React (или я зарежда чрез CDN) в администраторския панел, може да срещнете грешки, които са трудни за диагностициране, особено след актуализация на WordPress. WordPress вече предоставя необходимите пакети за редактора.

ПРЕДНА (счупена)

<?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 );
} );

СЛЕД (коригирано: използвайте WordPress пакети)

<?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
	);
} );

Полезна документация: пакет wp-element et Наръчник за блоков редактор.

Съвместимост с Divi 5 / Elementor / Avada

Диви 5 Ако активирате опции за производителност, които „оптимизират“ администраторския интерфейс, тествайте Gutenberg след това. Divi понякога зарежда редактори на ресурси за своите модули; изключете ги. /wp-admin/ агресивни оптимизации.
Elementor Въпреки че Elementor има собствен редактор, той се интегрира с администраторския панел на WordPress. Плъгин за оптимизация, който комбинира администраторски скриптове, може да наруши работата на Gutenberg и екрана на Elementor.
Avada Fusion Builder и Avada Live зареждат тежки скриптове. Ако имате процес на кеширане/минимизиране, който засяга администраторската област, Avada често е първият, който разкрива проблема.

Решение 3: Кеширане, сигурност и CSP (Content-Security-Policy), които нарушават администраторската

Когато видя, че Gutenberg работи само наполовина или само след хардуерно обновяване, подозирам проблем с кеша. Когато видя грешки „Отказва да се зареди… защото нарушава CSP“, подозирам лошо конфигурирани заглавки за сигурност.

Често срещан случай: оптимизация, която минимизира/обединява администраторския файл

Много плъгини за оптимизация имат опция „Оптимизирай и администраторската област“. В WordPress 6.9.4 това често е лоша идея: администраторската област се променя бързо, пакетите вече са оптимизирани и рискът от нарушаване на зависимостите е реален.

Конкретно действие:

Деактивиране на JS/CSS оптимизацията /wp-admin/.
Изключете поне:
- /wp-includes/js/dist/
- /wp-admin/js/
- load-scripts.php et load-styles.php (ако се използва)
Почистване: кеш на плъгини + кеш на сървъра + CDN + браузър.

Често срещан случай: Прекалено строг социално-икономически статус

„Високосигурен“ CSP може да блокира механизмите, използвани от издателя (в зависимост от плъгини, медии, iframe-ове и др.). Грешките се появяват в конзолата, а не в WordPress.

Пример за грешка в конзолата:

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

Ако управлявате CSP чрез PHP (плъгин за сигурност, персонализирани заглавки), тествайте, като разхлабите ограниченията само за администраторския панел. Ето един пример. минимален (да се адаптира и валидира с вашата политика за сигурност):

<?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 );

Защо се коригира Gutenberg и някои администраторски компоненти могат да използват URL адреси. blob: / data: (в зависимост от функциите и разширенията). Твърде рестриктивен CSP блокира зареждането/оценката и JS приложението не стартира.

Риск за сигурността : 'unsafe-inline' et 'unsafe-eval' Това увеличава риска от XSS. В идеалния случай не искате това. Но в действителност много WP стекове (включително плъгини) не са готови за перфектен „стриктно-динамичен“ CSP. Използвайте прогресивен CSP и режима Само отчет да итерирам.

Често срещан случай: ресурси от по-стара версия, предоставяни чрез CDN/opcache

След актуализация на WordPress, вече видях някои wp-includes/js/dist/* предоставяне на файлове от предишна версия чрез CDN. След това Gutenberg зарежда комбинация от несъвместими версии.

Контролен списък:

Изчистете CDN (а не само кеша на плъгините).
Изчистете PHP opcache-а, ако имате достъп (или рестартирайте PHP-FPM).
Проверете дали внедряването е качено успешно. всички WordPress файлове (особено чрез ръчен SFTP).

Проверки след корекция

Отворете съществуваща статия и създайте нова: и двата екрана би трябвало да работят.
Тествайте с акаунт Admin след това сметка Éditeur (REST възможностите се различават).
Конзола: нула Червена грешка при първоначално зареждане. Възможно е да има някои предупреждения, но няма блокираща грешка.
Мрежа: заявки /wp-json/ трябва да е във формат 200, а отговорът трябва да е във формат JSON.
Бърз тест за публикуване: чернова → публикуване → актуализиране.

Ако използвате Elementor/Divi/Avada, отворете и техните екрани за редактиране: „администраторски“ пач би трябвало да подобри цялото нещо, не само Gutenberg.

Ако това все още не работи

Процедурата, която прилагам, когато проблемът продължава (в този ред, защото избягва въртенето в кръг).

1) Режим на отстраняване на неизправности без да се засягат посетителите

Активиране Здравен преглед и използвайте режим на отстраняване на неизправности.
Деактивирайте всички плъгини в този режим, като запазите темата активна.
Опитай Гутенберг.

Ако това работи, активирайте отново плъгините един по един, докато не откриете виновника (често сигурност, кеш, оптимизация или лошо кодиран плъгин за персонализирани полета).

2) Проверете PHP лог файловете и REST грешките

отворено wp-content/debug.log веднага след неуспешно зареждане.
Търсене за: Fatal error, headers already sent, Deprecated (някои отхвърлени опции могат да замърсят изхода, ако се покажат), REST.

За да разберете грешките „невалиден JSON“, официалната документация за отстраняване на грешки е тук: Отстраняване на грешки в WordPress.

3) Монитор на заявки: проверка за грешки и AJAX/REST заявки

Query Monitor показва PHP грешки, куки и понякога HTTP извиквания. Когато отстранявам проблеми с Gutenberg, го използвам главно за:

за да се идентифицира предупреждение, което се задейства при REST заявка,
Идентифицирайте отговорния плъгин чрез трасирането на стека.
проверете дали администраторът зарежда някакви неочаквани скриптове.

4) Проверете състоянието на сайта и ограниченията на сървъра

PHP памет Gutenberg, конструкторите на софтуер и големите плъгини могат да причинят проблеми. Недостатъчната памет може да доведе до периодични сривове.
Ограничения : max_input_vars Твърде ниското може да повлияе на някои екрани (по-рядко на чист Gutenberg, повече на тежки мета-боксове).
Разрешения Ако основните WP файлове не могат да се четат, ще получите грешки 404/500 за ресурсите.

5) Нулиране на постоянни връзки (рядко, но бързо)

Когато REST връща грешки 404, въпреки че файлът съществува, съм виждал непоследователни правила за пренаписване след миграция.

Настройки → Постоянни връзки → Запазване (без промяна).

6) Проверете за конфликт на фрагменти

Плъгини за фрагменти (или functions.php) са основна причина, защото една проста синтактична грешка нарушава всичко.

Потърсете грешка „липсваща точка и запетая“ или грешка в скоби.
Проверете дали даден фрагмент се изпълнява на init / wp_loaded и направи echo / var_dump.

7) WP-CLI: Проверка на целостта и версиите

В сайт, където подозирам непълно внедряване, WP-CLI е много ефективен:

# 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

Документация на WP-CLI: WP-CLI команди.

Често срещани капани и грешки

симптом	Вероятна причина	Препоръчително решение
„Невалиден JSON отговор“ след добавяне на фрагмент	`echo`/`var_dump` или PHP предупреждение по време на REST	Изтрийте изхода, използвайте `error_log()`Правилни предупреждения (Решение 1)
Гутенберг се зарежда само в определени браузъри.	Кеш на браузъра/сервизен работник или разширение	Тествайте частното сърфиране, деактивирайте разширенията, изчистете кеша (Решение 3)
JS грешка „wp не е дефиниран“	Скриптът е зареден твърде рано или на грешен екран	Цел `post.php`/`post-new.php` + зависимости (Решение 2)
403 на `/wp-json/` само в производство	WAF/CDN, правило за ModSecurity, основно удостоверяване	Бял списък REST/admin-ajax, WAF логове, байпас (Решение 1)
Работи след деактивиране на кеша, след което отново се поврежда.	Плъгин за реактивна оптимизация „minify admin“	Изключете `/wp-admin/` и WP пакети (Решение 3)
Грешка след актуализация на WP, JS файловете показват 404	Незавършено внедряване / CDN обслужва старата версия	CDN Purge + `wp core verify-checksums` (Решение 3)
Кодът е „на правилното място“, но не работи.	Копирано в грешен файл (плъгин срещу дъщерна тема) или неподходяща кука	Добавяне към MU-плъгин, проверка на hook и приоритет
Прекъсва се само за ролята на редактор.	REST/nonce възможности, плъгин за роли	Тествайте REST маршрути с тази роля, коригирайте възможностите

Грешки, които често виждам сред средно напредналите потребители:

Тествайте директно в продукцията без резервно копие, след което спешно „поправете“.
Добавете откъс от стар урок (преди версия 6.x), който блокира REST „от съображения за сигурност“.
Забравяне да се изчисти кешът на CDN след актуализация на WordPress.
Използване на кука, която е твърде глобална (напр. init) за отпечатване на HTML или зареждане на JS.
Минифицирайте/конкатенирайте администраторския файл, „за да спестите 0,2 секунди“ и да загубите редактора.

Вариант / алтернатива

Метод без код: изолиране с проверка на състоянието + контролирано връщане към предишните настройки

Проверка на състоянието → режим на отстраняване на неизправности → деактивиране на плъгини по категория (сигурност/кеширане/оптимизация).
Ако виновникът бъде идентифициран, актуализирайте или заменете го.
Ако грешката е причинена от скорошна актуализация, извършете временно връщане назад (плъгин) и след това отворете заявка с издателя.

По-усъвършенстван метод: MU-плъгин „защита“ за регистриране на REST грешки

Когато даден сайт е сложен (Avada + Elementor + сигурност + кеш), понякога инсталирам временен MU-плъгин, за да регистрирам REST грешки, без да прекъсвам производителността.

<?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 );

Тази предпазна мярка помага за съпоставяне на повреден екран на Gutenberg с прецизен REST маршрут.

Избягвайте този проблем в бъдеще

Не блокирайте REST глобалноАко засилвате сигурността, направете го по маршрути, роли и контексти. Тествайте администратора след всяка промяна.
Не оптимизирайте администраторската част (минимизиране/комбиниране/отлагане), освен в много контролирани случаи. Печалбите са минимални, рисковете огромни.
Заредете правилно администраторските си скриптове :
- таргетиране на екрана ($hook_suffix + get_current_screen()),
- Зависимости wp-* декларира,
- надеждно версиране (filemtime в опростена среда).
Следете за PHP предупреждения В PHP 8.1+, някои модели задействат повече предупреждения/оставяния. Показано предупреждение може да наруши JSON.
Процес на актуализиране : подготовка → почистване на кешове → производство. И след актуализация на WordPress, систематично почистване на CDN.
Заглавки за сигурност : внедряване на CSP в Само отчет Първо, затягайте го постепенно. В противен случай ще „счупите администраторската част“ със следващия плъгин, който добавя iframe или blob.

Полезни PHP справки: Конфигурация за обработка на грешки в PHP.

ресурси

Често задавани въпроси

Защо Gutenberg показва „Отговорът не е валиден JSON отговор“?

Защото REST заявката очаква JSON, но получава нещо друго (HTML грешка 403/500, PHP предупреждение, нежелан изход). Отворете отговора в раздела „Мрежа“: често ще видите причината веднага.

Добра практика ли е деактивирането на REST API „поради съображения за сигурност“?

Не, не глобално. WordPress (и Gutenberg) го използват вътрешно. Ако го подсилвате, направете го по маршрут и като същевременно запазите функционалността на администраторския панел. Тествайте систематично. /wp-json/wp/v2/types/post?context=edit свържете се.

Защо работи за администратор, но не и за редактор?

Възможностите се различават и някои плъгини за роли/сигурност филтрират REST въз основа на ролята. Тествайте със съответния акаунт и проверете за грешки 403 в REST маршрутите в контекст. edit.

Може ли плъгин за кеширане да наруши работата на Gutenberg?

Да, особено ако кешира удостоверени REST крайни точки или ако оптимизира/минимизира администраторски скриптове. Изключи /wp-admin/ et /wp-json/ агресивни правила за кеширане.

Какво трябва да направя, ако получавам само грешка 500 на REST маршрут?

Това почти винаги е фатално PHP извикване, задействано по време на тази заявка. Разрешено WP_DEBUG_LOGвъзпроизвеждайте, след което наблюдавайте debug.logQuery Monitor помага да се идентифицира отговорният плъгин/тема.

Divi 5 / Elementor / Avada съвместими ли са с Gutenberg?

Да, но те добавят скриптове и опции за производителност. Конфликтите възникват главно от администраторски оптимизации, минифициране или прекалено строги правила за сигурност. Ако Gutenberg се повреди, тествайте и редактора на конструктора: причината често е споделена.

Ще помогне ли „повторното запазване на постоянните връзки“?

Понякога, ако REST върне грешки 404 след миграция или промяна на сървър, това не е първото нещо, което трябва да се направи, но е бързо и безрисково.

Мога ли да „поправя Гутенберг“, като презаредя jQuery или добавя персонализиран JS?

Това обикновено е временен вариант, който маскира истинския проблем (неработещ REST сървър, конфликтни скриптове). Отстранете причината: блокиране от REST, неправилно поставяне в опашката, проблеми с кеша/CDN или фатален PHP.

Кои файлове трябва да проверя, когато ресурсите на Gutenberg връщат грешка 404?

Разгледайте URL адресите wp-includes/js/dist/ et wp-includes/css/dist/Грешка 404 може да показва непълно внедряване или CDN, обслужващ по-стара версия. wp core verify-checksums помага много.

Виждам „Отказва зареждане… нарушава политиката за сигурност на съдържанието“. Какво да правя?

Облекчете CSP за администратора, в идеалния случай чрез Само отчет Първо, проверете указанията. script-src, style-src, connect-srcи разрешението на blob:/data: Ако е необходимо. Правете го постепенно, за да ограничите риска от XSS.

Гутенберг заседна: поправете блоковия редактор на WordPress

Проблемът

Бързо обобщение

Симптомите

Бърза диагностична диаграма

Защо се случва това?

Предварителни изисквания преди започване

Решение 1: REST API е блокиран (403/401/500) и Gutenberg вече не може да стартира

Диагностичен

Често срещан случай: плъгин блокира REST чрез прекалено агресивен филтър

ПРЕДНА (счупена)

СЛЕД (коригирано, целенасочено ограничение)

Често срещан случай: „Невалиден JSON отговор“ поради PHP предупреждение

ПРЕДНА (счупена)

СЛЕД (коригирано)

Често срещан случай: Блокиране на WAF/CDN (403, предизвикателство, Basic Authentication)

Решение 2: Неработещи скриптове на редактора (подреждане в опашка, зависимости, ред на зареждане)

Диагностичен

Често срещан случай: глобално проучване на admin_enqueue_scripts без да се насочвате към екрана

ПРЕДНА (счупена)

СЛЕД (коригирано: насочване + зависимости + версии)

Често срещан случай: плъгин ръчно зарежда React/ReactDOM

ПРЕДНА (счупена)

СЛЕД (коригирано: използвайте WordPress пакети)

Съвместимост с Divi 5 / Elementor / Avada

Решение 3: Кеширане, сигурност и CSP (Content-Security-Policy), които нарушават администраторската

Често срещан случай: оптимизация, която минимизира/обединява администраторския файл

Често срещан случай: Прекалено строг социално-икономически статус

Често срещан случай: ресурси от по-стара версия, предоставяни чрез CDN/opcache

Проверки след корекция

Ако това все още не работи

1) Режим на отстраняване на неизправности без да се засягат посетителите

2) Проверете PHP лог файловете и REST грешките

3) Монитор на заявки: проверка за грешки и AJAX/REST заявки

4) Проверете състоянието на сайта и ограниченията на сървъра

5) Нулиране на постоянни връзки (рядко, но бързо)

6) Проверете за конфликт на фрагменти

7) WP-CLI: Проверка на целостта и версиите

Често срещани капани и грешки

Вариант / алтернатива

Метод без код: изолиране с проверка на състоянието + контролирано връщане към предишните настройки

По-усъвършенстван метод: MU-плъгин „защита“ за регистриране на REST грешки

Избягвайте този проблем в бъдеще

ресурси

Често задавани въпроси

Защо Gutenberg показва „Отговорът не е валиден JSON отговор“?

Добра практика ли е деактивирането на REST API „поради съображения за сигурност“?

Защо работи за администратор, но не и за редактор?

Може ли плъгин за кеширане да наруши работата на Gutenberg?

Какво трябва да направя, ако получавам само грешка 500 на REST маршрут?

Divi 5 / Elementor / Avada съвместими ли са с Gutenberg?

Ще помогне ли „повторното запазване на постоянните връзки“?

Мога ли да „поправя Гутенберг“, като презаредя jQuery или добавя персонализиран JS?

Кои файлове трябва да проверя, когато ресурсите на Gutenberg връщат грешка 404?

Виждам „Отказва зареждане… нарушава политиката за сигурност на съдържанието“. Какво да правя?

Статии

Коментирай Отказване на отговора

Често срещан случай: глобално проучване на `admin_enqueue_scripts` без да се насочвате към екрана

Коментирай