本文详解 WooCommerce 自定义商品查询中分页失效、各页内容重复的根本原因及修复方法，重点指出误用 offset 导致分页逻辑崩溃，并提供基于 paged 参数的标准实践方案。
本文详解 woocommerce 自定义商品查询中分页失效、各页内容重复的根本原因及修复方法，重点指出误用 `offset` 导致分页逻辑崩溃，并提供基于 `paged` 参数的标准实践方案。
在 WooCommerce 主题开发或自定义商品列表页（如分类页、搜索页或专题页）中，若使用 WP_Query 手动查询商品并集成分页功能，却出现所有分页显示完全相同商品的问题——这并非模板渲染错误，而是分页参数配置不当引发的底层查询逻辑失效。
核心问题在于：手动设置 offset 会与 posts_per_page 冲突，彻底绕过 WordPress 分页机制。当开发者为实现“跳过前 N 条”而显式传入 'offset' => $n 时，WP_Query 将忽略 paged 参数，导致每次请求都从数据库起始位置取固定数量结果（如 posts_per_page=16），自然每页数据一致。
✅ 正确做法是完全弃用 offset，改用 paged + posts_per_page 组合，由 WordPress 自动计算偏移量。paged 参数会触发内部的 LIMIT M, N 计算（例如第 2 页、每页 16 条 → LIMIT 16, 16），确保分页语义准确。
以下是修正后的标准代码示例：
// ✅ 正确：使用 'paged' 实现原生分页
$product_args = [
'post_type' => 'product',
'post_status' => 'publish',
'orderby' => 'ID',
'order' => 'ASC',
'posts_per_page' => 16,
'paged' => max(1, get_query_var('paged')), // 关键！动态获取当前页码
'suppress_filters' => false, // 如需兼容 WPML/缓存插件请保留
];
$products = new WP_Query($product_args);
if ($products->have_posts()) :
while ($products->have_posts()) :
$products->the_post();
wc_get_template_part('content', 'product');
endwhile;
// ✅ 必须重置全局 $post 对象（尤其在主循环外调用时）
wp_reset_postdata();
// 渲染分页链接
echo paginate_links([
'base' => str_replace(999999999, '%#%', esc_url(get_pagenum_link(999999999))),
'format' => '?paged=%#%',
'current' => max(1, get_query_var('paged')),
'total' => $products->max_num_pages,
'mid_size' => 4,
'end_size' => 2,
'prev_next' => true,
'prev_text' => is_rtl() ? '→' : '←',
'next_text' => is_rtl() ? '←' : '→',
'type' => 'list',
]);
endif;
⚠️ 关键注意事项：
- wp_reset_postdata() 不可省略：它将全局 $post 恢复为主查询状态，避免后续模板（如页脚、侧边栏）误读自定义查询的数据；
- 勿混用 offset 与 paged：二者互斥，offset 会强制覆盖分页逻辑；
- get_query_var('paged') 需在主循环前调用：若在子页面或自定义重写规则下失效，可改用 get_query_var('page')（注意是 page 而非 paged）并配合 query_posts() 替代方案（不推荐）；
- 性能提示：对大数据集，建议启用对象缓存（如 Redis）并避免 suppress_filters => false 在高并发场景滥用。
总结：WooCommerce 分页重复的本质是脱离了 WordPress 的分页生命周期。坚持使用 paged 参数、配合 posts_per_page 和规范的 wp_reset_postdata()，即可零成本解决该问题，同时保障与 WooCommerce 核心、插件及主题的兼容性。
