使用自定义文章类型(CPT)分页时非首页返回404的问题排查

问题回顾 #

我基于Underscores Starter Theme开发WordPress主题，用PHP编写代码。在home.php和index.php里通过以下代码调用自定义文章类型my_cpt并实现分页：

global $wp_query; $wp_query = new WP_Query( array( 'post_type' => 'my_cpt', 'posts_per_page' => 8, 'paged' => $paged ) ); if ( $wp_query->have_posts() ) : while ( $wp_query->have_posts() ) : $wp_query->the_post(); //display the post .. which I did endwhile; //Pagination starts here $total_pages = $wp_query->max_num_pages; if ($total_pages > 1){ $current_page = max(1, get_query_var('paged')); echo paginate_links(array( 'base' => get_pagenum_link(1) . '%_%', 'format' => '/page/%#%', 'current' => $current_page, 'total' => $total_pages, 'prev_text' => __('« prev'), 'next_text' => __('next »'), )); } //Pagination ends here endif;

首页内容显示正常，但访问http://mywebsite/page/X（X为大于1的页码）时，网站直接显示404.php；删除主题中的404.php文件后，所有分页页面恢复正常。想咨询：是否存在配置遗漏？该现象是否符合正常逻辑？

现象分析：不符合正常逻辑 #

这个问题的核心是你直接替换了全局的$wp_query变量，干扰了WordPress的主查询判断，导致模板层级匹配出错：

• WordPress的模板选择逻辑是基于主查询结果的。当你访问/page/X时，主查询默认会去查找普通文章（post类型）的第X页，如果你的站点普通文章数量不足X页，主查询就会返回404状态，此时WordPress会优先加载主题里的404.php。
• 当你删掉404.php后，WordPress触发模板 fallback机制，会使用更通用的index.php或home.php，这时候你的自定义查询代码才会执行，显示出分页内容——但这只是治标不治本的临时解决方案。

正确解决方案 #

方案1：使用独立的自定义查询变量（不修改主查询）

不要直接替换全局$wp_query，改用自己的查询变量，并且记得重置查询状态：

// 定义自定义查询，不干扰全局变量
$custom_cpt_query = new WP_Query( array( 
    'post_type'      => 'my_cpt', 
    'posts_per_page' => 8, 
    'paged'          => get_query_var('paged') ? get_query_var('paged') : 1 
) ); 

if ( $custom_cpt_query->have_posts() ) : 
    while ( $custom_cpt_query->have_posts() ) : $custom_cpt_query->the_post(); 
        // 这里写你的文章内容显示代码
    endwhile; 

    // 分页逻辑，基于自定义查询的参数
    $total_pages = $custom_cpt_query->max_num_pages; 
    if ($total_pages > 1){ 
        $current_page = max(1, get_query_var('paged')); 
        echo paginate_links(array( 
            'base'      => get_pagenum_link(1) . '%_%', 
            'format'    => '/page/%#%', 
            'current'   => $current_page, 
            'total'     => $total_pages, 
            'prev_text' => __('« prev'), 
            'next_text' => __('next »'), 
        )); 
    } 
    wp_reset_postdata(); // 重置查询，避免影响后续的全局内容
endif;

方案2：修改主查询（推荐）

如果你的首页本来就应该显示自定义文章类型my_cpt，最好通过pre_get_posts钩子修改主查询，这样分页路由会完全匹配WordPress的规则：

// 在主题的functions.php中添加这段代码
add_action( 'pre_get_posts', 'customize_home_main_query' );
function customize_home_main_query( $query ) {
    // 仅在前台首页的主查询中生效
    if ( $query->is_home() && $query->is_main_query() && !is_admin() ) {
        $query->set( 'post_type', 'my_cpt' );
        $query->set( 'posts_per_page', 8 );
    }
}

之后在home.php或index.php里用默认的循环即可，分页也可以用原生函数：

if ( have_posts() ) : 
    while ( have_posts() ) : the_post(); 
        // 显示文章内容
    endwhile; 
    // 使用原生分页函数，更符合WordPress规范
    the_posts_pagination( array(
        'prev_text' => __('« prev'),
        'next_text' => __('next »'),
    ) );
endif;

最后一步：刷新固定链接

做完上述修改后，一定要去WordPress后台的「设置」→「固定链接」页面，点击「保存更改」，刷新固定链接规则，确保分页路由正确生效。

内容的提问来源于stack exchange，提问作者Aness