Чому мій блоковий шаблон не застосовується у WordPress?

Зазвичай тому, що збережена в базі даних копія перекриває файл. Щойно ви відредагували шаблон у Site Editor і натиснули Save, WordPress створює запис wp_template і віддає його замість файлу .html із теки вашої теми. Кожна наступна правка у файлі на сайті вже не видно.

Як змусити WordPress використовувати файл теми, а не версію із Site Editor?

Відкрийте Appearance, далі Editor, далі Templates, знайдіть шаблон і в меню його опцій скиньте налаштування або поверніть до початкового стану. Це видалить запис із бази даних і поверне контроль файлу на диску. Якщо меню пропонує Delete замість Reset, шаблон існує лише в базі даних і файлу за ним немає.

Де в темі WordPress мають лежати файли блокових шаблонів?

Повні шаблони — у теці templates у корені теми, а багаторазові фрагменти — у теці parts. Обидві використовують розширення .html, імена файлів у нижньому регістрі й дефіси замість підкреслень. Блоковій темі також обов'язково потрібен файл templates/index.html, інакше WordPress узагалі не вважатиме тему блоковою.

Яка різниця між шаблоном і частиною шаблону?

Шаблон формує цілу сторінку, і його обирає ієрархія шаблонів залежно від того, що переглядають. Частина шаблону — це фрагмент на кшталт шапки чи підвалу, який шаблон підтягує в себе. Редагування частини із шапкою змінює кожен шаблон, який її містить, — саме тому правки частин часто виглядають так, ніби застосувалися не там.

Чи може кеш заважати оновленню блокових шаблонів?

Іноді так, але це найменш імовірна причина, і перевіряти її варто останньою. Кеш сторінок і постійний об'єктний кеш можуть тримати застарілу розмітку, тож очистіть обидва, перш ніж робити висновки. Очищення OPcache тут не дає нічого, бо блокові шаблони — це файли .html, які PHP взагалі не компілює.

Чому мій шаблон за слагом сторінки перестав працювати?

Шаблони за слагом зіставляються зі слагом поточного запису під час запиту. Перейменування сторінки змінює її слаг, тож page-about.html тихо перестає збігатися, щойно сторінка стає about-us. Те саме стосується шаблонів рубрик і міток. Або перейменуйте файл під новий слаг, або призначте шаблон явно на бічній панелі редактора записів.

Блоковий шаблон WordPress не застосовується? Починайте з бази даних

Ваш файл шаблону майже напевно ігнорується тому, що перемагає копія в базі даних. Щойно ви відкриваєте шаблон у Site Editor і натискаєте Save, WordPress створює запис wp_template, і відтоді віддається саме він, а не файл .html із теки вашої теми, — тож кожна ваша подальша правка у файлі на сайті невидима. Видалити цей запис і є рішенням, і перевіряти це треба першим, ще до ієрархії, імені файлу чи кешу.

Переконайтеся, що копія в базі існує

Перейдіть до Appearance → Editor → Templates. Кожен шаблон, який WordPress віддає з бази даних, позначений у списку — залежно від версії WordPress напис читається як “Customized” або шаблон з’являється під фільтром “Customized”. Ця позначка і є вся відповідь. Якщо вона є, ваш файл не використовується.

Те саме можна перевірити з командного рядка — це швидше й працює навіть тоді, коли Site Editor поводиться дивно:

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.

Одна деталь, на якій спотикаються: ці записи прив’язані до теми через термін таксономії, а не через шлях. Якщо перейменувати теку теми, збережені шаблони лишаться в базі, але перестануть відповідати активній темі, і сайт різко відкотиться до файлів. Виглядає це як «мої налаштування зникли», а не як «мій файл ігнорується» — механізм той самий, симптом протилежний.

Приберіть її

У Site Editor відкрийте меню опцій шаблону (три крапки поруч із ним) і оберіть Clear customizations — у деяких версіях пункт зветься Reset. Це видалить запис із бази даних, і контроль повернеться до файлу на диску.

Якщо меню пропонує Delete замість Clear customizations чи Reset, цей шаблон існує лише в базі даних і файлу за ним немає. Видалення прибирає шаблон повністю, і WordPress відкочується вниз по ієрархії.

Через WP-CLI, використовуючи ID зі списку вище:

wp post delete 482 --force

Будьте чесні щодо ціни: скидання налаштувань безповоротно знищує все, що ви побудували в Site Editor для цього шаблону, і скасувати це неможливо. Якщо у версії із Site Editor є справжня робота, спершу скопіюйте блокову розмітку: відкрийте шаблон у редакторі, перемкніться на перегляд коду й вставте результат у свій файл .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`

Дві речі перекривають це повністю. Перша — запис у базі даних, описаний вище. Друга — шаблон, призначений безпосередньо запису чи сторінці: відкрийте редактор запису, знайдіть панель Template на бічній панелі й перевірте, чи не обрано там щось конкретне. Явне призначення перемагає ієрархію завжди, і побачити його можна, лише якщо спеціально піти й подивитися.

Шаблони за слагом крихкі так, що це варто запам’ятати назавжди. 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 не класифікує тему як блокову, і Site Editor може взагалі не з’явитися.
Якщо ви працюєте в дочірній темі, її шаблони мають пріоритет над батьківськими. Забутий файл у дочірній темі тихо переможе батьківський файл, який ви редагуєте.

Власні шаблони, які мають бути доступні для вибору в редакторі записів, треба ще й оголосити в theme.json у секції customTemplates — із базовим іменем файлу, зрозумілою людині назвою та типами записів, до яких вони застосовуються. Без цього запису файл існує, але в панелі Template ніколи не з’явиться.

Кеш — перевіряйте останнім

Кеш справді існує, але це найменш імовірна причина, і саме звертання до неї першою забирає у людей півдня.

Очистіть кеш сторінок, а якщо у вас працює постійний об’єктний кеш на кшталт Redis чи Memcached — скиньте і його: результати розв’язання шаблонів можуть зберігатися там. Потім перезавантажте сторінку з обходом кешу браузера.

Що не допоможе: очищення OPcache. Блокові шаблони — це файли .html, які PHP ніколи не компілює, тож OPcache до них не має жодного стосунку. Якщо колись очищення OPcache начебто це полагодило, тоді ж змінилося щось іще.

Досі не працює?

Якщо запису в базі даних немає, ім’я файлу правильне, шаблон запису явно не призначено, а кеші вже очищено — дивіться на плагіни. Будь-що, що фільтрує розв’язання шаблонів (конструктор сторінок, плагін членства, багатомовний плагін, LMS), може підставити власний шаблон пізно в межах запиту. Перемкніться на стандартну блокову тему й перевірте з вимкненими плагінами, а тоді вмикайте їх по одному.

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