Gutenberg завис: исправьте блочный редактор WordPress

паритет | 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, ошибка 404 в JS-файле) определяет все остальное.
  • Мгновенный тест REST : /wp-json/wp/v2/types/post?context=edit Затем, войдя в систему, сравните результаты с данными в учетной записи администратора.
  • Отключите помехи : плагины безопасности/кэширования, фрагменты кода, оптимизация JS/CSS, CDN, а затем активируйте их по одному.
  • Включить очистку журналов : WP_DEBUG_LOG + В мониторе запросов найдите «REST», «nonce», «headers already sent», «fatal».
  • Не стоит "исправлять" Gutenberg с помощью 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/... Отключить плагин/фрагмент кода. правильный Предупреждения см. в Решении 1.
403 на /wp-json/ WAF, правило безопасности, базовая аутентификация Тестирование REST в режиме приватного просмотра + журналы WAF Добавьте в белый список заголовки REST+, см. Решение 1.
Бесконечный вращающийся индикатор, ошибки JavaScript Неработающая очередь администратора / Оптимизация JavaScript Консоль: «Невозможно прочитать свойства неопределенного объекта» Корригер Добавить в очередь, исключить активы, см. Решение 2.
404 на wp-includes/js/dist/ Неполное развертывание / кэш CDN Проверьте работу, отключив CDN и очистив кэш. Удаление и повторное развертывание см. в Решении 3.
500 на дороге отдыха Fatal PHP (плагин/тема) WP_DEBUG_LOG + Монитор запросов Для исправления критических ошибок выполните откат, см. Решение 1.

Почему это происходит

Проще говоря: блочный редактор — это JavaScript-приложение, которое постоянно взаимодействует с вашим веб-сайтом через REST API. Если REST возвращает что-либо, кроме чистого JSON (или если необходимые скрипты не загружаются), редактор не может инициализировать свое состояние.

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

  • Gutenberg загружает пакеты из wp-includes/js/dist/ и стили администратора.
  • Он получает данные через REST-конечные точки (типы, таксономии, настройкиавтосохранения, послеИ т.д.).
  • Он отправляет аутентифицированные запросы с использованием одноразовых чисел (nonce). Если плагин изменяет заголовки, блокирует маршруты или кэширует ответы «контекста редактирования», это приводит к сбою.
  • PHP-предупреждение, «уведомление» или даже пробел перед чем-либо <?php Этого может быть достаточно, чтобы исказить JSON-ответ.

Вероятные причины (от наиболее частых до самых редких):

  1. Блокировка REST-запросов из-за безопасности/кэша/CDN (403, запрос, базовая аутентификация, правило ModSecurity).
  2. загрязненный REST-ответ из-за предупреждения PHP var_dump()или плагин, который выводит HTML-код.
  3. Оптимизация JS/CSS который объединяет/минимизирует административную панель (или «отложенные» скрипты WordPress).
  4. Плохо спроектированная очередь администратора (отсутствующие зависимости, неподходящий хук, глобальная загрузка на всех страницах).
  5. Заголовки CSP/безопасности слишком строгий (блокирует) blob:, data:или ожидаемые скрипты/стили).
  6. Несогласованность кэша (сервис-воркер, кэш браузера, кэш объектов, CDN), который предоставляет ресурсы из другой версии.
  7. Проблема с сервером (Права доступа к файлам, неполное развертывание, opcache, отсутствующее расширение PHP).

Предварительные условия перед началом обучения

  • охрана файлы + база данных (или снимок, если вы используете управляемый хостинг). Не проводите тестирование "случайным образом" в рабочей среде.
  • Тестовая среда В идеале — подготовка площадки или, по крайней мере, период технического обслуживания.
  • Версии Рекомендуется использовать WordPress 6.9.4 и PHP 8.1+. Зарегистрируйтесь. Инструменты → Состояние сайта.
  • Полезные плагины :
  • Журналы временно активировать 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 больше не может запуститься.

Когда Gutenberg не загружается, я всегда начинаю с простого REST-запроса. Потому что, если REST не работает, можно исправить все скрипты в мире: редактор останется нестабильным.

диагностический

  1. Откройте редактор от имени администратора, затем нажмите F12 → вкладка Сеть.
  2. Фильтр включен wp-json.
  3. Определите первый запрос, вызывающий ошибку (часто) types, settings, posts).
  4. Нажмите на запрос → просмотреть ответ :
    • Если вы видите HTML-код (страница ошибки, запрос на подтверждение, страница входа), значит, вы нашли то, что искали.
    • Если вы видите JSON-сообщение об ошибке WordPress, запишите его. code et message.

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

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

Если вы получаете ошибку 403/401 или ошибку HTML-страницы, причина почти всегда кроется вне WordPress (WAF, плагин безопасности, базовая аутентификация, обратный прокси).

Типичный случай: плагин блокирует 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;
} );

Почему это исправляет Gutenberg вызывает 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. Любой символ вывода (предупреждение, метка префикса, эхо) нарушает парсинг JSON на стороне браузера.

Типичная ситуация: блокировка WAF/CDN (ошибка 403, запрос подтверждения, базовая аутентификация).

Если в ответ на запрос 403 появляется HTML-страница с сообщением «Доступ запрещен» или запрос на подтверждение доступа, WordPress не несет за это ответственности.

  • Временно отключите WAF/CDN (или переключитесь в «режим разработчика»).
  • Явно разрешить /wp-json/ et /wp-admin/admin-ajax.php.
  • Если в тестовом режиме включена базовая аутентификация, Gutenberg может не работать в зависимости от настроек вашего браузера. В этом случае разрешите доступ с IP-адреса администратора или временно отключите базовую аутентификацию во время редактирования.

Чтобы разобраться в REST-контракте на стороне WordPress, ознакомьтесь с официальной документацией здесь: Справочник по REST API.

Решение 2: Неработающие скрипты редактора (enqueue, dependencies, load order)

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

  • на неправильном крючке,
  • без зависимостей,
  • или путем переопределения библиотеки (React, lodash), которая уже предоставляется WordPress.

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

диагностический

  1. F12 → Консоль: обратите внимание на Премьера ошибка (не пятнадцатая). Чаще всего причиной является первая.
  2. F12 → Сеть: поиск JS-файла с ошибкой 404/блокировка.
  3. Временно отключите плагины оптимизации (minify/combine/defer), влияющие на панель администратора.

Типичный пример: глобальное исследование по admin_enqueue_scripts без наведения на экран

Я часто видел, как повсюду загружается скрипт "администрирования", который предполагает наличие wp.data (Gutenberg) даже на экранах, которые его не загружают. Или, наоборот: он перезаписывает глобальные переменные.

ПЕРЕДНЯЯ ЧАСТЬ (сломана)

<?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.
  • Авада 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) блокирует загрузку/оценку, и приложение JavaScript не запускается.

Риск безопасности : 'unsafe-inline' et 'unsafe-eval' Это увеличивает риск XSS-атак. В идеале этого следует избегать. Но в реальности многие стеки WordPress (включая плагины) не готовы к идеальной «строго-динамической» CSP. Используйте прогрессивную CSP и режим Только отчет повторять.

Типичный случай: ресурсы из более старой версии, размещенные через CDN/opcache.

После обновления WordPress я уже кое-что увидел wp-includes/js/dist/* Gutenberg предоставляет доступ к файлам из предыдущей версии через CDN. Затем Gutenberg загружает смесь несовместимых версий.

Контрольный список:

  • Очистите CDN (а не только кэш плагинов).
  • Очистите кэш операций PHP, если у вас есть к нему доступ (или перезапустите PHP-FPM).
  • Убедитесь, что развертывание успешно загружено. все Файлы WordPress (особенно при передаче вручную по SFTP).

Проверки после внесения исправлений

  • Откройте существующую статью и создайте новую: оба варианта должны работать.
  • Тестирование с использованием учетной записи Админ затем счет Издатель (Возможности REST-запросов различаются).
  • Приставка : ноль Красная ошибка при первоначальной загрузке. Возможно наличие предупреждений, но критической ошибки нет.
  • Сеть: запросы /wp-json/ Значение должно быть 200, а ответ должен быть в формате JSON.
  • Быстрый тест публикации: черновик → публикация → обновление.

Если вы используете Elementor/Divi/Avada, откройте также их экраны редактирования: патч для «администрирования» должен улучшить работу всего приложения, а не только Gutenberg.

Если это всё ещё не поможет

Процедура, которую я применяю, когда проблема не исчезает (в таком порядке, чтобы избежать зацикливания).

1) Режим устранения неполадок без ущерба для посетителей

  • Включить Проверка работоспособности и использовать режим устранения неполадок.
  • В этом режиме отключите все плагины, оставив тему активной.
  • Попробуйте Gutenberg.

Если это поможет, активируйте плагины по одному, пока не найдете виновника (часто это плагины безопасности, кэширования, оптимизации или плохо написанный плагин пользовательских полей).

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, чаще на экранах с большим количеством мета-блоков).
  • Разрешения... Если основные файлы WordPress недоступны для чтения, вы получите ошибки 404/500 при работе с ресурсами.

5) Сброс постоянных ссылок (редко, но быстро)

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

  1. Настройки → Постоянные ссылки → Сохранить (без изменений).

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)
Gutenberg загружается только в некоторых браузерах. Кэширование браузера/сервис-воркер или расширение Проверьте режим приватного просмотра, отключите расширения, очистите кэш (Решение 3)
Ошибка JavaScript: «wp не определен» Скрипт загрузился слишком рано или на неправильном экране. нацеливание post.php/post-new.php + зависимости (Решение 2)
403 на /wp-json/ только в производстве WAF/CDN, правило ModSecurity, базовая аутентификация Внести в белый список REST/admin-ajax, журналы WAF, обход (Решение 1)
После отключения кэша всё работает, а затем снова ломается. Плагин реактивной оптимизации «minify admin» Исключать /wp-admin/ и пакеты WP (Решение 3)
Ошибка после обновления WordPress, файлы JavaScript выдают ошибку 404. Незавершенное развертывание / CDN обслуживает старую версию Очистка CDN + wp core verify-checksums (Решение 3)
Код находится «в нужном месте», но не работает. Скопировано в неправильный файл (плагин или дочерняя тема) или использован неподходящий хук. Добавить в MU-плагин, проверить хук и приоритет.
Сбой происходит только для роли редактора. Возможности REST/nonce, плагин ролей Протестируйте REST-маршруты с этой ролью и отрегулируйте необходимые возможности.

Часто встречающиеся ошибки среди пользователей среднего уровня:

  • Протестируйте непосредственно на рабочей среде без резервного копирования, затем срочно "исправьте".
  • Добавьте фрагмент кода из старого руководства (версии до 6.x), который блокирует REST «в целях безопасности».
  • Забыли очистить кэш CDN после обновления WordPress.
  • Использование слишком глобального хука (например, init) для вывода HTML-кода или загрузки JavaScript.
  • Сведите/объедините административный код, чтобы сэкономить 0,2 секунды, и уберите редактор.

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

Метод без использования кода: изоляция с проверкой состояния здоровья + контролируемый откат

  • Проверка работоспособности → режим устранения неполадок → отключение плагинов по категориям (безопасность/кэширование/оптимизация).
  • Если виновник обнаружен, обновите или замените его.
  • Если ошибка вызвана недавним обновлением, выполните временный откат (плагина), а затем откройте заявку в службу поддержки у издателя.

Более продвинутый метод: плагин MU «safeguard» для регистрации ошибок 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, а получает что-то другое (ошибка 403/500 HTML, предупреждение 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 не работает, протестируйте также редактор-конструктор: причина часто бывает одинаковой.

Поможет ли функция "повторное сохранение постоянных ссылок"?

Иногда, если после миграции или смены сервера REST-запрос возвращает ошибку 404, это не первое, что следует сделать, но это быстро и безопасно.

Можно ли "исправить Gutenberg", перезагрузив jQuery или добавив собственный JavaScript?

Обычно это временное решение, маскирующее реальную проблему (неисправный 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-атак.

Статьи по Теме

Оставьте комментарий

Ваш электронный адрес не будет опубликован. Обязательные для заполнения поля помечены *

Этот сайт использует Akismet для уменьшения нежелательности. Узнайте больше о том, как обрабатываются данные ваших отзывов.