本文详解 WordPress 中使用 WP_Query 实现自定义分页时常见的“始终显示第一页内容”问题，核心原因在于 offset 参数与 paged 逻辑冲突、next_posts_link() 未正确传入查询对象最大页数，以及分页函数作用域错误。提供可直接复用的修复代码与关键原理说明。
本文详解 wordpress 中使用 `wp_query` 实现自定义分页时常见的“始终显示第一页内容”问题，核心原因在于 `offset` 参数与 `paged` 逻辑冲突、`next_posts_link()` 未正确传入查询对象最大页数，以及分页函数作用域错误。提供可直接复用的修复代码与关键原理说明。
在 WordPress 主题开发中，当使用 WP_Query 手动构建分类归档页并启用分页时，一个高频陷阱是：第二页及后续页面持续显示与第一页完全相同的内容。这并非缓存或服务器问题，而是由分页参数设计缺陷导致的逻辑错误。本文将从原理到实践，系统性解决该问题。
? 根本原因分析
问题代码中存在两个关键错误：
offset 与 paged 冲突
'offset' => 5 强制跳过前 5 篇文章，但 WP_Query 在分页模式下（即设置了 'paged'）会自动计算起始位置（OFFSET = (paged - 1) * posts_per_page）。此时手动指定 offset 会覆盖分页偏移逻辑，导致所有分页请求均基于“跳过前 5 篇后的固定起点”取数据，从而失去分页意义。next_posts_link() 未绑定查询对象
原代码中调用 next_posts_link( 'Next Page ', $the_query->max_num_pages )，但 $the_query 未定义（应为 $all_catPosts），且 next_posts_link() 默认作用于主查询（$wp_query），对自定义查询无效。必须显式传入 WP_Query 实例的 max_num_pages，并配合 get_next_posts_link() 或正确使用 paginate_links()。previous_posts_link() 同样需上下文
同理，previous_posts_link() 在自定义查询中无法自动识别当前分页状态，需确保 $paged > 1 判断准确，并推荐改用更可控的 paginate_links()。
✅ 正确实现方案（含修复代码）
移除 offset，改用标准分页参数；修正分页函数调用，绑定自定义查询对象：
<?php
$cat = get_the_category();
$cat_name = !empty($cat) ? esc_html($cat[0]->name) : '';
$paged = get_query_var('paged') ? (int) get_query_var('paged') : 1;
$args = array(
'post_type' => 'post',
'post_status' => 'publish',
'category_name' => $cat_name,
'posts_per_page' => 16,
'paged' => $paged, // ✅ 关键：启用分页
'orderby' => 'date',
'order' => 'DESC',
// ❌ 移除 'offset' => 5 —— 分页已通过 'paged' 自动处理
);
$all_catPosts = new WP_Query($args);
?>
<?php if ($all_catPosts->have_posts()) : ?>
<div class="min-h-screen flex items-center justify-center">
<div class="grid grid-cols-4 gap-4">
<?php while ($all_catPosts->have_posts()) : $all_catPosts->the_post(); ?>
<div class="p-5 rounded big_cat_container">
<section>
<a class="thumbnail_img" href="<?php the_permalink(); ?>">
<?php the_post_thumbnail('medium'); ?>
</a>
</section>
<h4 class="post_title">
<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
</h4>
</div>
<?php endwhile; ?>
</div>
<!-- ✅ 使用 paginate_links() 实现健壮分页 -->
<?php if ($all_catPosts->max_num_pages > 1) : ?>
<nav class="pagination mt-8" role="navigation">
<?php
echo paginate_links(array(
'base' => add_query_arg('paged', '%#%'),
'format' => '',
'current' => $paged,
'total' => $all_catPosts->max_num_pages,
'prev_text' => __('← Previous', 'textdomain'),
'next_text' => __('Next →', 'textdomain'),
'type' => 'list',
'end_size' => 1,
'mid_size' => 2,
));
?>
</nav>
<?php endif; ?>
</div>
<?php endif; ?>
<?php wp_reset_postdata(); // ✅ 恢复全局 $post 对象 ?>⚠️ 注意事项与最佳实践
- 永远避免在分页查询中混用 offset：若需跳过前 N 篇（如置顶文章），应通过 post__not_in 或自定义 SQL 过滤，而非 offset。
- paginate_links() 是首选：相比 next_posts_link()，它支持任意 WP_Query 对象，样式可控，语义清晰。
- 安全兜底：使用 !empty($cat) 防止无分类时出错；$paged 强制 (int) 类型转换，防范注入风险。
- 性能提示：posts_per_page => 16 属合理范围；若数据量极大，建议配合 cache_results => true（默认开启）和对象缓存插件。
- 主题兼容性：确保当前模板文件（如 category.php 或自定义模板）未被其他插件或 pre_get_posts 钩子干扰分页逻辑。
✅ 总结
WordPress 自定义分页失效，90% 源于 offset 干扰分页计算，或分页函数未正确关联查询实例。牢记三原则：不手动 offset、用 paged 参数驱动分页、用 paginate_links() 绑定 WP_Query->max_num_pages。修复后，每页将严格返回对应范围的 16 篇文章，分页链接也具备完整导航能力——这是专业 WordPress 开发者必须掌握的基础分页范式。
