WooCommerce 自定义商品查询中分页失效、各页内容重复，通常是因错误使用 offset 而未正确传递 paged 参数所致；本文详解如何通过标准化 WP_Query 分页参数 + 正确重置机制，实现稳定、可扩展的分页功能。
woocommerce 自定义商品查询中分页失效、各页内容重复，通常是因错误使用 `offset` 而未正确传递 `paged` 参数所致；本文详解如何通过标准化 wp_query 分页参数 + 正确重置机制，实现稳定、可扩展的分页功能。
在 WooCommerce 主题开发或自定义商品列表（如按条件筛选、首页精选等场景）中，开发者常通过 WP_Query 手动查询商品。但若分页逻辑配置不当，极易出现「所有分页显示完全相同商品」的问题——表面看是 paginate_links() 渲染正常，实则后端查询始终返回第一页数据。
根本原因在于：WP_Query 的分页必须依赖 paged 参数驱动内部 SQL 的 LIMIT 和 OFFSET 计算。若手动设置 offset，会绕过 WordPress 的分页逻辑，导致 max_num_pages 计算错误、get_query_var('paged') 失效，且与主循环冲突。
✅ 正确做法是：移除 offset，改用 paged + posts_per_page 组合，由 WordPress 自动计算偏移量：
// ✅ 正确：使用 'paged' 参数（注意：值需从 query var 安全获取）
$product_args = [
'post_type' => 'product',
'post_status' => 'publish',
'orderby' => 'ID',
'order' => 'ASC',
'posts_per_page' => 16,
'paged' => max(1, get_query_var('paged', 1)), // 关键！支持静态首页和自定义页面
'suppress_filters' => false, // 如需兼容 WooCommerce 筛选钩子，保持为 false
];
$products = new WP_Query($product_args);
if ($products->have_posts()) {
while ($products->have_posts()) {
$products->the_post();
wc_get_template_part('content', 'product');
}
wp_reset_postdata(); // ✅ 此处无需传参，全局重置即可
} else {
wc_get_template('loop/no-products-found');
}
// 分页链接生成（推荐使用 get_pagenum_link 避免 URL 冲突）
$pagination = 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,
'prev_text' => is_rtl() ? '→' : '←',
'next_text' => is_rtl() ? '←' : '→',
'type' => 'list',
]);
if ($pagination) {
echo '<nav class="woocommerce-pagination">' . $pagination . '</nav>';
}
⚠️ 关键注意事项：
- wp_reset_postdata() 不接受参数：传入 $products 是无效写法（该函数仅重置全局 $post），应直接调用 wp_reset_postdata()；
- paged 值必须来自 get_query_var('paged')：在非标准归档页（如 page 模板），需确保重写规则已生效（可通过 flush_rewrite_rules() 临时验证，上线后务必移除）；
- 若在 pre_get_posts 中修改主查询，请勿在此处重复新建 WP_Query，避免逻辑冲突；
- suppress_filters => false 是 WooCommerce 兼容性必需项，否则可能丢失库存、价格等动态过滤逻辑。
? 进阶提示：如需支持 AJAX 分页，应在 wp_ajax_ 回调中复用相同 $product_args 结构，并通过 wp_send_json() 返回 HTML 片段及 max_num_pages，前端再动态注入并更新分页容器。
遵循此模式，即可彻底解决 WooCommerce 自定义商品页分页重复问题，同时保障与 WooCommerce 核心功能（如排序、筛选、库存状态）的无缝集成。
