Почему блочный шаблон не применяется в WordPress?

Обычно потому, что сохранённая копия в базе данных перекрывает файл. Как только вы отредактировали шаблон в редакторе сайта и нажали «Сохранить», WordPress создал запись типа wp_template и отдаёт её вместо файла .html из папки темы. Все последующие правки файла на сайте не видны.

Как заставить WordPress использовать файл темы вместо версии из редактора сайта?

Откройте «Внешний вид → Редактор → Шаблоны», найдите нужный шаблон и в его меню действий выберите сброс пользовательских изменений. Это удалит запись из базы и вернёт управление файлу на диске. Если в меню предлагается «Удалить», а не «Сбросить», шаблон существует только в базе данных и файла за ним нет.

Где в теме WordPress лежат файлы блочных шаблонов?

Полные шаблоны — в папке templates в корне темы, повторно используемые фрагменты — в папке parts. И там и там расширение .html, имена файлов строчными буквами и через дефис, а не через подчёркивание. Кроме того, блочной теме обязательно нужен файл templates/index.html, иначе WordPress вообще не признает тему блочной.

Чем шаблон отличается от части шаблона?

Шаблон отрисовывает страницу целиком и выбирается иерархией шаблонов исходя из того, что просматривается. Часть шаблона — это фрагмент вроде шапки или подвала, который шаблон подключает. Правка части-шапки меняет все шаблоны, которые её включают, — поэтому кажется, что изменения применились не туда.

Может ли кэширование мешать обновлению блочных шаблонов?

Иногда да, но это наименее вероятная причина, и проверять её надо в последнюю очередь. Кэш страниц и постоянный объектный кэш способны держать устаревшую разметку, так что очистите оба, прежде чем делать выводы. Сброс OPcache здесь бесполезен: блочные шаблоны — это файлы .html, PHP их никогда не компилирует.

Почему перестал работать шаблон вида page-slug?

Шаблоны по слагу сопоставляются со слагом текущей записи в момент запроса. Переименовали страницу — сменился слаг, и page-about.html молча перестаёт совпадать, как только страница стала about-us. То же самое с шаблонами рубрик и меток. Либо переименуйте файл под новый слаг, либо назначьте шаблон явно в боковой панели редактора записи.

Блочный шаблон WordPress не применяется? Начните с базы данных

Ваш файл шаблона почти наверняка игнорируется, потому что побеждает копия в базе данных. Стоит открыть шаблон в редакторе сайта и нажать «Сохранить», как WordPress создаёт запись типа wp_template, и с этого момента отдаётся именно она, а не файл .html из папки темы — поэтому все последующие правки файла на сайте не видны. Удаление этой записи и есть решение, и проверять это нужно первым делом, до иерархии, имён файлов и кэша.

Убедитесь, что копия в базе существует

Зайдите в «Внешний вид → Редактор → Шаблоны». Любой шаблон, который WordPress отдаёт из базы данных, помечен в списке — в зависимости от версии это либо метка «Изменён», либо отдельный фильтр с таким названием. Эта метка и есть весь ответ. Если она есть, ваш файл не используется.

То же самое можно проверить из командной строки — быстрее, и работает даже когда редактор сайта капризничает:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Каждая строка — переопределение из базы данных. Значение post_name совпадает со слагом шаблона, поэтому строка с именем single перекрывает templates/single.html.

Одна деталь, на которой спотыкаются: эти записи привязаны к теме через элемент таксономии, а не через путь. Переименуете папку темы — сохранённые шаблоны останутся в базе, но перестанут совпадать с активной темой, и сайт резко откатится к файлам. Выглядит это как «мои правки исчезли», а не «мой файл игнорируется» — механизм тот же, симптом противоположный.

Удалите её

В редакторе сайта откройте меню действий шаблона (три точки рядом с ним) и выберите сброс пользовательских изменений — в некоторых версиях пункт называется «Сбросить». Это удалит запись из базы, и управление вернётся файлу на диске.

Если вместо сброса меню предлагает «Удалить», значит, этот шаблон существует только в базе данных и файла за ним нет. Удаление уберёт шаблон целиком, и WordPress откатится вниз по иерархии.

Через WP-CLI, взяв ID из списка выше:

wp post delete 482 --force

Будьте честны с собой насчёт цены: сброс безвозвратно уничтожает всё, что вы собрали в редакторе сайта для этого шаблона, и отменить это нельзя. Если в версии из редактора есть реальная работа, сначала вытащите блочную разметку — откройте шаблон в редакторе, переключитесь в режим кода и вставьте результат в свой файл .html. Так файл становится источником истины, и ничего не теряется.

Как WordPress выбирает шаблон

Блочные темы используют ту же логику иерархии, что и классические, только с файлами .html в templates/ вместо файлов .php в корне темы. WordPress идёт от самого частного к самому общему и берёт первый существующий файл.

Что просматривается	Порядок проверки
Отдельная запись	`single-post-{slug}.html` → `single-post.html` → `single.html` → `singular.html` → `index.html`
Страница	`page-{slug}.html` → `page-{id}.html` → `page.html` → `singular.html` → `index.html`
Архив рубрики	`category-{slug}.html` → `category-{id}.html` → `category.html` → `archive.html` → `index.html`
Произвольный тип записи	`single-{post-type}.html` → `single.html` → `singular.html` → `index.html`
Страница 404	`404.html` → `index.html`

Две вещи перебивают всё это целиком. Первая — запись в базе данных, описанная выше. Вторая — шаблон, назначенный напрямую записи или странице: откройте редактор записи, найдите в боковой панели раздел «Шаблон» и проверьте, не выбрано ли там что-то конкретное. Явное назначение всегда сильнее иерархии, и заметить его можно, только если специально посмотреть.

Шаблоны по слагу хрупки так, что это стоит запомнить. page-about.html совпадает лишь до тех пор, пока слаг страницы — about. Переименуйте страницу в about-us, и шаблон перестанет применяться без предупреждений и без ошибок.

Шаблон против части шаблона

Шаблон отрисовывает целое представление и выбирается иерархией. Часть шаблона — фрагмент: шапка, подвал, сайдбар, — который шаблоны подключают. Части лежат в parts/, шаблоны — в templates/, а в базе данных они хранятся отдельно, как записи wp_template_part.

Типичная путаница: вы правите шапку, и изменение появляется на страницах, которые вы трогать не собирались. Это правильное поведение. Одну часть использует каждый шаблон, который её включает. Нужна другая шапка на одном шаблоне — заведите второй файл части и шаблон, который на неё ссылается; правкой общей части добиться различий по шаблонам невозможно.

Бывает и обратное. Вы кладёте макет целой страницы в parts/ и удивляетесь, почему иерархия его не подхватывает. Части вообще не участвуют в иерархии; напрямую на них ничего никогда не направляется.

Имена и расположение файлов

Проверьте это, прежде чем предполагать что-то более экзотическое:

Папка называется templates/, во множественном числе, в корне темы. Не template/ и не block-templates/. Название block-templates/ было верным во времена плагина Gutenberg, до того как блочные темы попали в ядро, и его до сих пор показывают многие туториалы — в актуальном WordPress оно не работает.
Части шаблонов лежат в parts/, а не в template-parts/ (это соглашение классических тем для PHP-частей).
Расширение — .html. Файл .php в templates/ игнорируется.
Имена файлов — строчными буквами и через дефис. single-Post.html или single_post.html не совпадут. На файловой системе без учёта регистра, например в macOS, это работает локально и ломается на Linux-сервере — классическое «у меня на машине работает».
Файл templates/index.html обязан существовать. Без него WordPress не считает тему блочной, и редактор сайта может вообще не появиться.
Если вы работаете в дочерней теме, её шаблоны приоритетнее родительских. Забытый файл в дочерней теме тихо перебьёт родительский файл, который вы правите.

Произвольные шаблоны, которые должны выбираться в редакторе записей, нужно ещё и объявить в theme.json в разделе customTemplates, указав базовое имя файла, понятный человеку заголовок и типы записей, к которым он применяется. Без этой записи файл существует, но в панели «Шаблон» никогда не появится.

Кэширование — проверяйте последним

Кэширование существует, но это наименее вероятная причина, и попытка начать с неё — верный способ потерять полдня.

Очистите кэш страниц и, если у вас постоянный объектный кэш вроде Redis или Memcached, сбросьте и его: результаты разрешения шаблонов могут храниться там. Затем перезагрузите страницу в обход кэша браузера.

Что точно не поможет — сброс OPcache. Блочные шаблоны — это файлы .html, PHP их никогда не компилирует, так что OPcache к ним отношения не имеет. Если однажды вам показалось, что сброс OPcache это починил, — значит, в тот же момент изменилось что-то ещё.

Всё равно не работает?

Если записи в базе нет, имя файла верное, явного назначения шаблона у записи нет, а кэши уже очищены — смотрите плагины. Всё, что фильтрует разрешение шаблонов: конструктор страниц, плагин членства, мультиязычный плагин, LMS — способно подставить свой шаблон поздно в ходе запроса. Переключитесь на стандартную блочную тему и проверьте с отключёнными плагинами, затем включайте их по одному.

А если шаблон применяется, но отрисовывается пустым — это уже другая проблема: проверьте, корректна ли блочная разметка в файле, потому что сломанный комментарий блока заставляет редактор молча вырезать содержимое вместо того, чтобы выдать ошибку.