Иерархия шаблонов WordPress: Полное техническое руководство

WordPress's Template Hierarchy — это детерминированная система разрешения шаблонов, которую WordPress использует для выбора PHP-файла шаблона, отвечающего за отображение конкретного запроса страницы. Когда посетитель загружает любой URL на вашем сайте, WordPress оценивает контекст запроса — тип записи, таксономию, slug, ID и другие параметры — затем проходит по приоритетному списку имён файлов-кандидатов, пока не найдёт совпадение в директории активной темы. Если конкретный шаблон не найден, происходит откат к index.php.

Глубокое понимание этой системы обязательно для серьёзной разработки на WordPress. Это основа каждого пользовательского макета, каждого переопределения темы и каждой оптимизации производительности, связанной с кэшированием шаблонов. Независимо от того, управляете ли вы контентным изданием, магазином WooCommerce или headless-установкой WordPress, иерархия определяет, какой PHP-код выполняется при каждой загрузке страницы.

Что такое Template Hierarchy на самом деле

По своей сути Template Hierarchy — это цепочка поиска, встроенная в ядро WordPress (wp-includes/class-wp-query.php и wp-includes/template.php). Когда WordPress завершает разбор запроса и заполнение глобального объекта $wp_query, он внутренне вызывает эквиваленты get_template_part() для определения правильного шаблона. Разрешение не случайно — это строгий упорядоченный список имён файлов, проверяемых в корневой директории вашей темы.

Ключевое архитектурное понимание, которое упускает большинство руководств: WordPress не сканирует директорию вашей темы. Он формирует приоритетный массив имён файлов-кандидатов на основе переменных запроса, затем проверяет каждый файл с помощью locate_template(). Это различие важно при отладке отсутствующих шаблонов или создании программных генераторов тем.

Цепочка откатов всегда завершается на index.php. Этот файл — единственный файл шаблона, который WordPress требует включать в каждую тему согласно стандартам разработки тем.

Основные файлы шаблонов, которые должна понимать каждая тема

Обратите внимание на запись singular.php — это шаблон, который многие разработчики полностью упускают из виду. Введённый в WordPress 4.3, он располагается между single.php/page.php и index.php в иерархии, выступая единым перехватчиком для любого отображения отдельного контента. Если ваша тема включает singular.php, он будет перехватывать случаи, когда не существует ни single.php, ни page.php.

Полный порядок разрешения шаблонов по типу страницы

Отдельные записи блога

Когда посетитель запрашивает стандартную запись (post_type = 'post'), WordPress проверяет в следующем точном порядке:

single-post-{slug}.php (WordPress 4.4+, например, single-post-hello-world.php)
single-post.php

1. single.php
2. singular.php
3. index.php

Вариант на основе slug на шаге 1 редко документируется, но чрезвычайно полезен для придания одной ключевой записи полностью уникального макета без изменения каких-либо других шаблонов.

Пользовательские типы записей

Для пользовательского типа записи, зарегистрированного как portfolio:

1. single-portfolio-{slug}.php
2. single-portfolio.php
3. single.php
4. singular.php
5. index.php

Для его архива (требуется 'has_archive' => true в register_post_type()):

1. archive-portfolio.php
2. archive.php
3. index.php

Распространённая ошибка: регистрация пользовательского типа записи с 'has_archive' => false (по умолчанию) и последующее недоумение, почему archive-portfolio.php никогда не загружается. URL архива в этом случае просто возвращает 404.

Статические страницы

1. Файл шаблона, заданный через мета-блок атрибутов страницы (пользовательский шаблон страницы)
2. page-{slug}.php
3. page-{ID}.php
4. page.php
5. singular.php
6. index.php

Пользовательские шаблоны страниц — это PHP-файлы в директории вашей темы, содержащие комментарий-заголовок файла:

<?php
/**
 * Template Name: Full Width Layout
 * Template Post Type: page
 */

Объявление Template Post Type (WordPress 4.7+) ограничивает типы записей, которые могут использовать этот шаблон из редактора. Без него шаблон отображается в выпадающем списке атрибутов страницы только для страниц.

Архивы категорий

1. category-{slug}.php
2. category-{ID}.php
3. category.php
4. archive.php
5. index.php

Архивы пользовательских таксономий

Для таксономии, зарегистрированной как genre, с slug термина thriller:

1. taxonomy-genre-thriller.php
2. taxonomy-genre.php
3. taxonomy.php
4. archive.php
5. index.php

Архивы авторов

1. author-{user_nicename}.php
2. author-{user_ID}.php
3. author.php
4. archive.php
5. index.php

Главная страница (критический граничный случай)

Это наиболее непонятная часть иерархии. WordPress различает два сценария главной страницы:

Сценарий A — Индекс записей блога в качестве главной страницы (Настройки > Чтение: «Последние записи»):

1. front-page.php
2. home.php
3. index.php

Сценарий B — Статическая страница в качестве главной страницы (Настройки > Чтение: «Статическая страница»):

1. front-page.php

page.php (если front-page.php не существует)
index.php

Критический нюанс: front-page.php имеет приоритет в обоих сценариях. Если front-page.php существует в вашей теме, он всегда отображает главную страницу независимо от настроек чтения. Это удивляет многих разработчиков, которые создают front-page.php для статической главной страницы, но забывают, что он также переопределит индекс блога при последующем изменении настройки.

Результаты поиска и 404

Результаты поиска:

1. search.php
2. index.php

Страницы ошибки 404:

1. 404.php
2. index.php

Хорошо проработанный 404.php — это актив для конверсии, а не второстепенный элемент. Он должен включать форму поиска, ссылки на популярный контент и чёткую навигацию — всё это требует понимания системы шаблонов для правильной реализации.

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

Понимание внутренней механики помогает при отладке или расширении системы. Процесс разрешения в wp-includes/template.php работает следующим образом:

// Simplified representation of WordPress template resolution
function get_query_template( $type, $templates = array() ) {
    $type = preg_replace( '|[^a-z0-9-]+|', '', $type );

    if ( empty( $templates ) ) {
        $templates = array( "{$type}.php" );
    }

    // Fires before template resolution — allows plugins/themes to modify the list
    $templates = apply_filters( "_{$type}_template_hierarchy", $templates );

    $template = locate_template( $templates );

    // Fires after template is located — allows final override
    $template = apply_filters( "{$type}_template", $template, $type, $templates );

    return $template;
}

Здесь критически важны два хука фильтров:

_{$type}_template_hierarchy — срабатывает до поиска файла, позволяя добавлять дополнительных кандидатов в массив
{$type}_template — срабатывает после нахождения файла, позволяя полностью заменить путь к разрешённому шаблону

Именно с помощью этих хуков плагины конструкторов страниц, мультисайтовые сети и WooCommerce переопределяют шаблоны без изменения файлов темы.
Программное переопределение иерархии шаблонов
Внедрение пользовательского пути к шаблону
add_filter( 'single_template_hierarchy', function( $templates ) {
    // Prepend a plugin-directory template before theme templates are checked
    if ( is_singular( 'portfolio' ) ) {
        array_unshift( $templates, plugin_dir_path( __FILE__ ) . 'templates/single-portfolio.php' );
    }
    return $templates;
} );
Переопределение шаблона после разрешения
add_filter( 'template_include', function( $template ) {
    if ( is_singular( 'portfolio' ) && current_user_can( 'edit_posts' ) ) {
        // Load a debug template for editors
        $debug_template = get_stylesheet_directory() . '/debug/single-portfolio-debug.php';
        if ( file_exists( $debug_template ) ) {
            return $debug_template;
        }
    }
    return $template;
} );
Фильтр template_include — это последний хук перед загрузкой файла шаблона WordPress. Он получает полностью разрешённый путь и должен вернуть допустимый путь к файлу.
Части шаблонов и функция get_template_part()
Части шаблонов — это повторно используемые PHP-фрагменты, загружаемые через get_template_part(). Они следуют собственной мини-иерархии:
// Loads content-video.php if it exists, falls back to content.php
get_template_part( 'template-parts/content', 'video' );
WordPress 5.5 добавил третий параметр для передачи данных в части шаблонов:
get_template_part( 'template-parts/card', 'product', array(
    'post_id' => get_the_ID(),
    'show_price' => true,
) );
Внутри части шаблона получите эти данные с помощью:
$args = wp_parse_args( $args, array(
    'post_id'    => 0,
    'show_price' => false,
) );
Это устраняет необходимость использования глобальных переменных для передачи данных между шаблонами — значительное улучшение с точки зрения поддерживаемости и тестируемости.
Дочерние темы и система переопределения шаблонов
Дочерние темы расширяют иерархию, добавляя директорию дочерней темы в начало пути поиска шаблонов. Когда выполняется locate_template(), проверяются:

Директория дочерней темы (get_stylesheet_directory())
Директория родительской темы (get_template_directory())

Это означает, что вы можете переопределить любой шаблон родительской темы, создав файл с идентичным именем в дочерней теме. Вам не нужно копировать весь файл — только те части, которые вы хотите изменить — но WordPress загружает файл как единое целое, поэтому вы должны включить всю необходимую разметку.
Распространённая ошибка с дочерними темами: Копирование functions.php из родительской темы в дочернюю с ожиданием, что он заменит функции родительской темы. В отличие от других файлов шаблонов, functions.php в дочерней теме загружается в дополнение к родительскому functions.php, а не вместо него. Оба файла выполняются.
Для создания минимальной структуры дочерней темы:
my-child-theme/
├── style.css          (required — contains theme header comment)
├── functions.php      (optional — enqueue parent styles here)
└── single-post.php    (overrides parent's single-post.php)
Заголовок style.css должен объявлять родителя:
/*
 Theme Name: My Child Theme
 Template: parent-theme-directory-name
*/
Отладка активного шаблона
Метод 1: Плагин Query Monitor
Плагин Query Monitor (бесплатный, WordPress.org) отображает разрешённый файл шаблона и полную иерархию кандидатов в панели панели администратора. Это наиболее надёжный инструмент отладки с минимальными накладными расходами.
Метод 2: Хук template_include
add_filter( 'template_include', function( $template ) {
    if ( current_user_can( 'manage_options' ) ) {
        echo '<!-- Template: ' . esc_html( str_replace( ABSPATH, '', $template ) ) . ' -->';
    }
    return $template;
} );
Это выводит путь к шаблону в виде HTML-комментария, видимого только администраторам. Удалите его перед развёртыванием в продакшн.
Метод 3: WP_DEBUG и логирование
На сервере разработки включите логирование отладки в wp-config.php:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Затем добавьте временное логирование внутри template_include:
add_filter( 'template_include', function( $template ) {
    error_log( 'Resolved template: ' . $template );
    return $template;
} );
В среде VPS Хостинга с root-доступом вы можете отслеживать лог отладки в реальном времени:
tail -f /var/www/html/wp-content/debug.log
Этот подход значительно надёжнее, чем использование браузерных инструментов отладки при устранении проблем с разрешением шаблонов на рабочем или тестовом сервере.
WooCommerce и система переопределения шаблонов
WooCommerce поставляется с собственной иерархией шаблонов, надстроенной над нативной системой WordPress. Шаблоны WooCommerce находятся в wp-content/plugins/woocommerce/templates/ и загружаются через собственную функцию wc_get_template(), которая проверяет переопределения в:

wp-content/themes/your-theme/woocommerce/

Чтобы переопределить шаблон отдельного товара WooCommerce, скопируйте woocommerce/templates/single-product.php в your-theme/woocommerce/single-product.php. Никогда не редактируйте файлы шаблонов плагина напрямую — они перезаписываются при каждом обновлении плагина.

WooCommerce также использует хуки действий woocommerce_template_single_*, что даёт вам детальный контроль над отдельными секциями (цена, вкладки, кнопка добавления в корзину) без переопределения целых файлов шаблонов. Это предпочтительный подход для незначительных изменений.

Блочные темы и иерархия шаблонов в Full Site Editing

WordPress 5.9 представил Full Site Editing (FSE) с блочными темами, что изменило практическую работу иерархии шаблонов. Блочные темы хранят шаблоны как HTML-файлы в директории templates/, а не как PHP-файлы:

my-block-theme/
├── templates/
│   ├── index.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
└── theme.json

Логика разрешения следует тем же правилам иерархии, но теперь WordPress также проверяет базу данных на наличие пользовательских шаблонов, сохранённых через редактор сайта. Порядок поиска становится следующим:

1. Сохранённый пользователем шаблон в базе данных (тип записи wp_template)
2. HTML-файл в директории templates/ темы
3. HTML-файл в директории templates/ родительской темы
4. Встроенные резервные шаблоны WordPress

Классические PHP-темы и блочные темы могут сосуществовать в одной установке WordPress, но нельзя смешивать PHP-шаблоны и HTML-шаблоны блоков в рамках одной темы. Если ваша тема имеет директорию templates/ и допустимый theme.json, WordPress считает её блочной темой.

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

Влияние иерархии шаблонов на производительность

Каждое разрешение шаблона включает проверки файловой системы через locate_template(). На высоконагруженном сайте это может добавить ощутимые накладные расходы при отсутствии кэширования. Ключевые оптимизации:

Кэширование объектов: Используйте постоянный кэш объектов (Redis или Memcached) для кэширования результатов WP_Query и сокращения количества запросов к базе данных, влияющих на выбор шаблона.

OPcache: Убедитесь, что PHP OPcache включён и правильно настроен. Поскольку шаблоны являются PHP-файлами, OPcache компилирует их в байт-код при первой загрузке и обслуживает последующие запросы из памяти. На правильно настроенном VPS с cPanel OPcache обычно включён по умолчанию, но может потребовать настройки opcache.memory_consumption и opcache.max_accelerated_files для крупных тем с большим количеством файлов шаблонов.

Избегайте лишних файлов шаблонов: Каждый файл шаблона в директории вашей темы является кандидатом, который должен проверить locate_template(). Темы с сотнями файлов шаблонов (характерно для раздутых коммерческих тем) увеличивают I/O файловой системы при каждом некэшированном запросе. Проведите аудит вашей темы и удалите неиспользуемые шаблоны.

Полное кэширование страниц: Инструменты вроде WP Rocket, W3 Total Cache или кэширование на уровне сервера (Nginx FastCGI cache, Varnish) полностью обходят выполнение PHP-шаблонов для анонимных пользователей. Разрешение иерархии шаблонов выполняется только при промахе кэша.

Практические паттерны кастомизации

Паттерн 1: Макет для конкретной категории без плагина

Создайте category-news.php в директории вашей темы. WordPress автоматически использует его для архива категории «news». Никаких плагинов, никаких хуков фильтров — только файл с правильным именем.

<?php
/**
 * Template for the "news" category archive.
 * Inherits from: category.php → archive.php → index.php
 */
get_header();
?>
<main class="news-archive">
    <h1><?php single_cat_title(); ?></h1>
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
        <?php get_template_part( 'template-parts/card', 'news' ); ?>
    <?php endwhile; endif; ?>
    <?php the_posts_pagination(); ?>
</main>
<?php get_footer(); ?>

Паттерн 2: Макет для конкретного автора среди избранных авторов

// author-jane-smith.php — loads only for the author with nicename "jane-smith"
get_header();
?>
<div class="featured-author-layout">
    <?php get_template_part( 'template-parts/author', 'featured' ); ?>
    <!-- Custom bio section, social links, etc. -->
</div>
<?php get_footer(); ?>

Паттерн 3: Условная логика внутри index.php

Если вы создаёте минималистичную тему и хотите избежать множества файлов шаблонов, вы можете использовать условные теги внутри index.php:

<?php get_header(); ?>

<?php if ( is_front_page() && is_home() ) : ?>
    <?php get_template_part( 'template-parts/home', 'blog-index' ); ?>
<?php elseif ( is_front_page() ) : ?>
    <?php get_template_part( 'template-parts/home', 'static' ); ?>
<?php elseif ( is_single() ) : ?>
    <?php get_template_part( 'template-parts/content', get_post_type() ); ?>
<?php elseif ( is_archive() ) : ?>
    <?php get_template_part( 'template-parts/archive', 'default' ); ?>
<?php else : ?>
    <?php get_template_part( 'template-parts/content', 'none' ); ?>
<?php endif; ?>

<?php get_footer(); ?>

Этот паттерн используется такими темами, как Twenty Twenty-One, и является полностью допустимым. Компромисс заключается в том, что единый большой index.php становится сложнее поддерживать по мере роста сложности.

Мультисайт и иерархия шаблонов

В сети WordPress Multisite каждый сайт в сети может использовать разные активные темы. Иерархия шаблонов работает одинаково для каждого сайта, но плагины, активированные на уровне сети, могут использовать фильтры template_include или _{$type}_template_hierarchy для внедрения общих шаблонов на всех сайтах без дублирования файлов темы.

Распространённый паттерн мультисайта — директория «сетевых шаблонов» за пределами корня веб-сервера, на которую ссылаются через хуки фильтров на уровне плагина. Это позволяет центральной команде дизайна одновременно распространять обновления шаблонов на все сайты — значительное операционное преимущество для агентств, управляющих десятками клиентских сайтов в единой среде Общего веб-хостинга или VPS.

SSL, безопасность и права доступа к файлам шаблонов

Файлы шаблонов являются PHP и должны рассматриваться как исполняемый код. Неправильные права доступа к файлам — распространённый вектор атак. На Linux-сервере файлы шаблонов темы должны принадлежать пользователю веб-сервера (обычно www-data или nginx) и иметь права 644:

find /var/www/html/wp-content/themes/your-theme -type f -name "*.php" -exec chmod 644 {} ;
find /var/www/html/wp-content/themes/your-theme -type d -exec chmod 755 {} ;

Никогда не устанавливайте права 777 для PHP-файлов. Если файлу шаблона требуется доступ на запись (нетипично и в целом нежелательно), используйте 664 с правильным групповым владением.

Сочетание вашей установки WordPress с действующим SSL-сертификатом гарантирует, что контент, отображаемый шаблонами — включая динамически генерируемые страницы с конфиденциальными данными пользователей — всегда передаётся по HTTPS. Это обязательное требование для любого сайта, использующего контактные формы, учётные записи пользователей или электронную коммерцию.

Справочник по иерархии шаблонов: визуальная схема

Request URL
    |
    v
WordPress Query Resolution (WP_Query)
    |
    +-- Is it the front page?
    |       front-page.php → home.php → index.php
    |
    +-- Is it a single post?
    |       single-{type}-{slug}.php → single-{type}.php → single.php → singular.php → index.php
    |
    +-- Is it a static page?
    |       [custom template] → page-{slug}.php → page-{ID}.php → page.php → singular.php → index.php
    |
    +-- Is it a category archive?
    |       category-{slug}.php → category-{ID}.php → category.php → archive.php → index.php
    |
    +-- Is it a custom taxonomy?
    |       taxonomy-{tax}-{term}.php → taxonomy-{tax}.php → taxonomy.php → archive.php → index.php
    |
    +-- Is it an author archive?
    |       author-{nicename}.php → author-{ID}.php → author.php → archive.php → index.php
    |
    +-- Is it a date archive?
    |       date.php → archive.php → index.php
    |
    +-- Is it search results?
    |       search.php → index.php
    |
    +-- Is it a 404?
            404.php → index.php

Матрица решений: когда использовать какой подход к кастомизации

Ключевые технические выводы

• index.php обязателен. Каждая тема должна его включать. Это универсальный откат, завершающий каждую цепочку разрешения.
• singular.php — недооценённый промежуточный уровень. Он перехватывает любую отдельную запись или страницу, когда не существует ни single.php, ни page.php. Используйте его в минималистичных темах для сокращения количества файлов.
• front-page.php переопределяет всё для главной страницы, независимо от настроек чтения. Если он существует, он загружается — всегда.
• Имена файлов чувствительны к регистру на Linux-серверах. Category-News.php не совпадёт, когда WordPress ищет category-news.php. Это скрытый сбой, который сложно отладить без Query Monitor.
• Фильтр template_include — главное переопределение. Он срабатывает после завершения всего разрешения иерархии и даёт вам последнюю возможность заменить любой шаблон по любой причине.
• Блочные темы хранят шаблоны как HTML, а не PHP. Логика иерархии идентична, но формат файлов и структура директорий принципиально отличаются от классических тем.
• functions.php дочерней темы загружается в дополнение к родительскому, а не вместо него. Все остальные файлы шаблонов следуют стандартному паттерну переопределения.
• Настройка OPcache важна при масштабировании. На высоконагруженных сайтах убедитесь, что opcache.max_accelerated_files превышает общее количество PHP-файлов в вашей установке WordPress, включая все файлы шаблонов темы.
• Шаблоны WooCommerce находятся за пределами иерархии WordPress. Они требуют отдельного рабочего процесса переопределения через поддиректорию woocommerce/ в вашей теме.
• Сочетайте работу по кастомизации шаблонов с правильно настроенным доменом и Регистрацией домена для обеспечения согласованности канонических URL на всех страницах, отображаемых шаблонами.

FAQ

Что происходит, если WordPress не может найти ни одного файла шаблона в иерархии?

WordPress всегда находит index.php, поскольку он обязателен для каждой допустимой темы. Если index.php отсутствует, WordPress выдаёт фатальную ошибку и отображает пустую страницу или ошибку сервера. Это единственный файл шаблона, отсутствие которого полностью нарушает работу сайта.

Можно ли использовать иерархию шаблонов в плагине без изменения активной темы?

Да. Используйте фильтр _{$type}_template_hierarchy для добавления пути к директории плагина в начало массива кандидатов до выполнения locate_template(), или используйте template_include для замены разрешённого пути к шаблону после разрешения. Именно так WooCommerce, bbPress и большинство крупных плагинов внедряют собственные шаблоны без необходимости изменения темы.

Почему front-page.php переопределяет индекс блога, даже когда в настройках чтения выбрано «Последние записи»?

Потому что front-page.php имеет безусловный приоритет для главной страницы при любых настройках чтения. Если вы хотите, чтобы индекс блога использовал home.php, переименуйте или удалите front-page.php из вашей темы. Внутри front-page.php используйте is_home() для определения того, является ли главная страница также индексом блога, и отображайте контент соответствующим образом.

Как узнать, какой файл шаблона WordPress в данный момент использует для конкретной страницы?

Установите плагин Query Monitor. Он отображает разрешённый путь к шаблону и полную иерархию кандидатов в панели администратора при каждой загрузке страницы. Как вариант, добавьте временный фильтр template_include, выводящий путь в виде HTML-комментария, видимого только администраторам.

Работает ли иерархия шаблонов одинаково в WordPress Multisite?

Логика разрешения для каждого сайта идентична. Каждый сайт разрешает шаблоны относительно своей активной темы. Разница на уровне сети: плагины, активированные на уровне сети, могут использовать хуки фильтров для внедрения общих шаблонов на всех сайтах, а функция get_stylesheet_directory() возвращает правильный путь для активной темы каждого отдельного сайта, а не общий сетевой путь.