WordPress自定义主题分页不显示 内置分页函数无效

核心问题原因 #

所有WordPress原生分页函数（the_posts_pagination()/paginate_links()/previous_posts_link()等）默认依赖全局主查询$wp_query存储的分页上下文（当前页码、总文章数、每页篇数）渲染分页组件，原代码存在3个直接导致分页失效的问题：

• 写死'offset' => 0，分页场景下偏移量需要随当前页码动态计算，写死0永远拉取第一页的9篇文章
• 自定义get_posts()查询未传入分页相关参数，且设置'suppress_filters' => true拦截了全局过滤器，查询结果不会同步到全局分页上下文
• 自定义循环结束后未调用wp_reset_postdata()重置全局文章对象，可能干扰后续全局数据读取

解决方案 #

方案1：使用原生主循环（官方推荐，兼容性最优） #

文章列表/归档页不需要手动调用get_posts()拉取文章，直接使用WordPress全局主循环即可自动适配后台阅读设置、分页规则，所有原生分页函数可直接正常调用。
模板代码替换为如下内容：

<div class="row">
  <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
    <div class="col-md-4 col-sm-12 mt-3">
      <div class="bg-gray h-100 blog-cards">
        <a href="<?php echo get_the_permalink();  ?>" title="more">
          <div>
            <div class="archive-img">
              <?= get_the_post_thumbnail(); ?>
            </div>
            <h3 class="upper mb-0 px-3 pt-3 pb-0 text-dark"> <?php echo get_the_title(); ?></h3>
            <div class="p-3 pt-0">
              <?php the_excerpt();  ?>
              <?php
              foreach (get_the_category(get_the_ID()) as $category) {
                echo '<a href="' . get_category_link($category->term_id) . '">' . $category->name . '</a>';
              } ?> |
              <span>
                مدت زمان مطالعه
                <?= get_field('duration'); ?>
                دقیقه
              </span>
            </div>
          </div>
        </a>
      </div>
    </div>
  <?php endwhile; ?>
  <!-- 分页组件直接调用即可正常渲染 -->
  <?php
  the_posts_pagination(array(
    'prev_text' => '上一页',
    'next_text' => '下一页',
  ));
  ?>
  <?php else : ?>
    <p>暂无发布文章</p>
  <?php endif; ?>
</div>

如果需要固定每页显示9篇文章，不需要在模板查询中硬编码，在主题functions.php中添加如下过滤器即可：

// 控制首页文章列表每页显示9篇
function custom_list_posts_per_page($query) {
  if ($query->is_main_query() && is_home()) {
    // 可根据需求扩展判断条件，比如is_archive()适配分类/标签归档页
    $query->set('posts_per_page', 9);
  }
}
add_action('pre_get_posts', 'custom_list_posts_per_page');

方案2：保留自定义get_posts查询，手动配置分页参数 #

如果业务逻辑必须保留自定义文章查询，需要手动获取当前页码、计算偏移量与总页数，再将参数传入分页函数完成渲染，参考代码如下：

<div class="row">
  <?php
  // 获取当前页码
  $paged = (get_query_var('paged')) ? absint(get_query_var('paged')) : 1;
  $per_page = 9;
  $args = array(
    'posts_per_page'   => $per_page,
    'offset'           => ($paged - 1) * $per_page, // 动态计算当前页偏移量
    'orderby'          => 'post_date',
    'order'            => 'DESC',
    'post_type'        => 'post',
    'post_status'      => 'publish',
    'suppress_filters' => false,
    'paged'            => $paged
  );
  $myposts = get_posts($args);
  // 计算总页数
  $total_posts = wp_count_posts('post')->publish;
  $total_pages = ceil($total_posts / $per_page);

  foreach ($myposts as $post) : setup_postdata($post); ?>
    <div class="col-md-4 col-sm-12 mt-3">
      <div class="bg-gray h-100 blog-cards">
        <a href="<?php echo get_the_permalink();  ?>" title="more">
          <div>
            <div class="archive-img">
              <?= get_the_post_thumbnail(); ?>
            </div>
            <h3 class="upper mb-0 px-3 pt-3 pb-0 text-dark"> <?php echo get_the_title(); ?></h3>
            <div class="p-3 pt-0">
              <?php the_excerpt();  ?>
              <?php
              foreach (get_the_category($post->ID) as $category) {
                echo '<a href="' . get_category_link($category->term_id) . '">' . $category->name . '</a>';
              } ?> |
              <span>
                مدت زمان مطالعه
                <?= get_field('duration'); ?>
                دقیقه
              </span>
            </div>
          </div>
        </a>
      </div>
    </div>
  <?php endforeach;
  wp_reset_postdata(); // 自定义循环结束必须重置全局文章对象
  // 传入分页参数渲染分页组件
  echo paginate_links(array(
    'total' => $total_pages,
    'current' => $paged,
    'prev_text' => '上一页',
    'next_text' => '下一页'
  ));
  ?>      
</div>

排查校验顺序 #

• 优先检查模板是否使用自定义get_posts/WP_Query替代了主循环，列表/归档页场景优先替换为原生主循环+pre_get_posts修改查询参数的写法，符合WordPress开发规范，可避免90%以上的分页、上下文相关问题
• 若必须使用自定义查询，校验是否正确获取当前页码、动态计算偏移量，循环结束是否调用wp_reset_postdata()
• 调用分页函数时确认是否传入了正确的总页数、当前页参数，无参数调用默认读取主查询数据，自定义查询场景下无法正常工作
• 分页逻辑修改完成后，可到后台固定链接设置页面重新保存一次规则，避免固定链接规则不更新导致的分页404问题

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