2026年5月25日

WordPressのテンプレート階層を理解する方法・どのファイルが使われるか

テーマ・デザイン

はじめに

「カテゴリーページだけデザインを変えたい」「特定の投稿タイプに専用テンプレートを使いたい」——WordPressのテンプレート階層を理解すると、ファイル名を変えるだけでページごとに異なるデザインを適用できます。

症状・原因

「single.phpを作ったのに特定の投稿タイプに反映されない」「カテゴリー別にデザインを変えたいが方法が分からない」という問題は、テンプレート階層の優先順位を知らないことが原因です。WordPressは特定から汎用の順でテンプレートを探します。

解決手順

ステップ1：テンプレート階層の基本ルールを理解する

WordPressは特定のファイルから汎用のファイルの順でテンプレートを探し、最初に見つかったファイルを使用します。

【投稿ページ（single）の探索順】
1. single-{post_type}-{slug}.php   例: single-news-hello-world.php
2. single-{post_type}.php          例: single-news.php
3. single.php
4. singular.php
5. index.php                       ← 最終フォールバック（必須）

【固定ページ（page）の探索順】
1. {カスタムページテンプレート}    テンプレートヘッダーで指定
2. page-{slug}.php                 例: page-about.php
3. page-{id}.php                   例: page-42.php
4. page.php
5. singular.php
6. index.php

【カテゴリーページの探索順】
1. category-{slug}.php             例: category-news.php
2. category-{id}.php               例: category-3.php
3. category.php
4. archive.php
5. index.php

【タームページ（カスタムタクソノミー）の探索順】
1. taxonomy-{taxonomy}-{term}.php  例: taxonomy-genre-rock.php
2. taxonomy-{taxonomy}.php         例: taxonomy-genre.php
3. taxonomy.php
4. archive.php
5. index.php

ステップ2：投稿タイプ別テンプレートを作成する

// カスタム投稿タイプ「news」を登録
add_action( 'init', function() {
    register_post_type( 'news', [
        'label'     => 'ニュース',
        'public'    => true,
        'has_archive' => true,
        'rewrite'   => [ 'slug' => 'news' ],
        'supports'  => [ 'title', 'editor', 'thumbnail', 'excerpt' ],
    ] );
} );

<?php
// single-news.php: ニュース投稿専用テンプレート
get_header(); ?>

<main id="main">
  <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

    <article class="news-single">
      <div class="news-header">
        <span class="news-date"><?php the_date( 'Y年m月d日' ); ?></span>
        <h1><?php the_title(); ?></h1>
      </div>

      <?php if ( has_post_thumbnail() ) : ?>
        <?php the_post_thumbnail( 'large' ); ?>
      <?php endif; ?>

      <div class="news-content">
        <?php the_content(); ?>
      </div>
    </article>

  <?php endwhile; endif; ?>
</main>

<?php get_footer(); ?>

ステップ3：カテゴリー別テンプレートを作成する

<?php
// category-news.php: "news"カテゴリー専用テンプレート
// URLが /category/news/ の場合に使用される
get_header(); ?>

<main id="main">
  <div class="news-archive-header">
    <h1>ニュース一覧</h1>
  </div>

  <div class="news-grid">
    <?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

      <article class="news-card">
        <?php the_post_thumbnail( 'medium' ); ?>
        <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
        <time><?php the_date( 'Y.m.d' ); ?></time>
        <?php the_excerpt(); ?>
      </article>

    <?php endwhile; endif; ?>
  </div>

  <?php the_posts_pagination(); ?>
</main>

<?php get_footer(); ?>

ステップ4：template_includeフィルターでカスタム制御する

// PHPでテンプレート選択をカスタマイズ
add_filter( 'template_include', function( $template ) {
    // ログインしていない場合は会員限定テンプレートを使用
    if ( is_singular( 'members' ) && ! is_user_logged_in() ) {
        $custom = locate_template( 'single-members-locked.php' );
        if ( $custom ) {
            return $custom;
        }
    }

    // 特定のタグが付いている投稿に専用テンプレートを使用
    if ( is_single() && has_tag( 'featured' ) ) {
        $custom = locate_template( 'single-featured.php' );
        if ( $custom ) {
            return $custom;
        }
    }

    return $template;
} );

ステップ5：使用中のテンプレートを確認する

// デバッグ用：どのテンプレートが使われているか表示
add_action( 'wp_head', function() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    global $template;
    echo '<!-- Active template: ' . basename( $template ) . ' -->';
} );

# WP-CLIでテンプレート階層を確認
# （Query Monitorプラグインでも視覚的に確認可能）

# テーマのテンプレートファイル一覧を確認
ls wp-content/themes/my-theme/*.php

# カスタム投稿タイプのアーカイブURLを確認
wp post-type list --fields=name,has_archive,rewrite_slug

# パーマリンクをフラッシュ（テンプレートが反映されない場合）
wp rewrite flush

注意事項

index.phpはテンプレート階層の最終フォールバックです。このファイルは必ず存在する必要があります。テーマにindex.phpがない場合、WordPressはそのテーマを認識しません。
カスタム投稿タイプのアーカイブページはarchive-{post_type}.phpで制御できます。has_archive => trueでカスタム投稿タイプを登録している場合に有効です。
テンプレートファイルを追加・変更した後、パーマリンク設定を保存し直す（wp rewrite flush相当）と反映されることがあります。特にカスタム投稿タイプやカスタムタクソノミーを新規登録した場合は必須です。

まとめ

テンプレート階層は「特定ファイルから汎用ファイルへの探索順」で動作します。single-{post_type}.php・category-{slug}.php・taxonomy-{taxonomy}.phpのようなファイル名規則に従うだけで、ページ種別ごとのデザインを柔軟に制御できます。関連記事：WordPressのテーマ開発入門、WordPressでカスタムページテンプレートを作成する方法。

Post Views: 28