WordPress 6.8分类归档WP_Query分页末页404问题求助

问题概述 #

在WordPress 6.8中，通过自定义WP_Query实现分类归档分页时，访问分页末页会出现404错误，仅末页受影响。调整后台「阅读设置」中「博客页面至多显示」参数与自定义查询的posts_per_page一致时可临时规避，但需从根源解决问题。

环境信息 #

• WordPress版本：6.8
• PHP版本：8.4.6
• MySQL版本：Ver 15.1 Distrib 10.11.11-MariaDB, for debian-linux-gnu (x86_64) using EditLine wrapper
• 服务器版本：Apache/2.4.62 (Debian)
• 本地与远程共享主机环境均出现该问题
• 测试主题：Twenty Twenty-Five、Twenty Twenty-Four、Twenty Twenty-Three（默认主题）
• 测试期间无插件激活
• 已覆盖登录/未登录状态测试

复现步骤 #

• 全新安装WordPress 6.8并配置新数据库
• 登录后台创建分类「food」
• 发布11篇文章并分配至「food」分类
• 在当前主题目录创建category-food.php文件
• 进入「设置」>「阅读」，保持「博客页面至多显示」为10篇
• 保存固定链接设置（无需修改）并验证.htaccess文件有效性

预期行为 #

• 分页功能正常，可访问所有分类归档页面
• 末页根据WP_Query的posts_per_page参数显示剩余文章，无404错误
  • /category/food/page/1/：显示4篇文章
  • /category/food/page/2/：显示4篇文章
  • /category/food/page/3/：显示3篇文章（共11篇）

实际行为 #

• /category/food/page/1/：正常显示4篇文章
• /category/food/page/2/：正常显示4篇文章
• /category/food/page/3/：返回404错误页面
• 仅分页末页出现问题
• 单独修改WP_Query参数无法解决根本问题
• 将「博客页面至多显示」设为与WP_Query的posts_per_page值一致可避免错误

原因分析 #

WordPress处理请求时先执行主查询，再加载自定义模板：

1. 主查询使用后台「阅读设置」中的posts_per_page（10）计算总页数：ceil(11/10)=2，因此认为page/3/是无效页码，直接触发404。
2. 自定义WP_Query使用自己的posts_per_page（4）计算总页数：ceil(11/4)=3，但此时主查询已经返回404，自定义查询的结果无法生效。
3. 即使自定义查询能获取到末页内容，主查询的404判定优先级更高，会直接输出404页面。

解决方案 #

方案一：通过pre_get_posts钩子调整主查询参数（推荐） #

在主题的functions.php中添加以下代码，让分类归档的主查询使用自定义的posts_per_page，确保主查询与自定义查询的总页数一致：

add_action('pre_get_posts', 'adjust_food_category_posts_per_page');
function adjust_food_category_posts_per_page($query) {
    // 仅针对主查询、food分类归档页面生效
    if (!is_admin() && $query->is_main_query() && is_category('food')) {
        $query->set('posts_per_page', 4);
    }
}

修改后的category-food.php可直接使用主查询结果（无需自定义WP_Query）：

<?php
get_header();

global $wp_query;
$paged = get_query_var('paged') ? get_query_var('paged') : 1;

echo '<pre>当前页码: ' . $paged . ', 总页数: ' . $wp_query->max_num_pages . ', 总文章数: ' . $wp_query->found_posts . '</pre>';

$html = '<ul>';
if (have_posts()) {
    while (have_posts()) {
        the_post();
        $html .= '<li><h3>' . esc_html(get_the_title()) . '</h3></li>';
    }
    $html .= '</ul>';
    
    // 添加分页导航
    the_posts_pagination(array(
        'mid_size' => 2,
        'prev_text' => __('上一页', 'textdomain'),
        'next_text' => __('下一页', 'textdomain'),
    ));
} else {
    echo '<p>暂无文章</p>';
}

echo $html;

get_footer();

方案二：修正404状态（临时备选） #

如果无法调整主查询参数，可通过template_redirect钩子强制取消404状态，但此方法不够优雅：

add_action('template_redirect', 'fix_food_category_last_page_404');
function fix_food_category_last_page_404() {
    if (is_category('food') && is_404()) {
        global $wp_query;
        // 重新计算自定义查询的总页数
        $custom_query = new WP_Query(array(
            'category_name' => 'food',
            'posts_per_page' => 4,
            'no_found_rows' => false,
        ));
        $max_pages = $custom_query->max_num_pages;
        $paged = get_query_var('paged') ? get_query_var('paged') : 1;
        
        // 如果当前页码在自定义查询的有效范围内，取消404
        if ($paged <= $max_pages) {
            status_header(200);
            $wp_query->is_404 = false;
        }
        wp_reset_postdata();
    }
}

关键说明 #

• 不要忽略WordPress的主查询优先级，自定义查询仅应作为主查询的补充，而非替代归档页面的核心逻辑。
• 使用pre_get_posts调整主查询是WordPress官方推荐的最佳实践，能彻底避免主查询与自定义查询的分页冲突。

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