在 WordPress 主题开发中，使用 get_posts() 无法触发内置分页函数（如 the_posts_pagination()），因其不修改全局 $wp_query 对象；需改用 WP_Query 并传入 paged 参数，才能使分页正常工作。
在 wordpress 主题开发中，使用 `get_posts()` 无法触发内置分页函数（如 `the_posts_pagination()`），因其不修改全局 `$wp_query` 对象；需改用 `wp_query` 并传入 `paged` 参数，才能使分页正常工作。
在 WordPress 中实现可靠、语义化且兼容主题功能的分页，关键在于正确使用查询对象与全局查询上下文。你当前代码中调用 get_posts() 是一个“独立查询”——它返回一组文章数组，但完全绕过了主循环（Main Loop）机制，因此 $wp_query 中的分页元数据（如总文章数 found_posts、当前页码 paged、每页数量 posts_per_page）均未被设置。这导致 the_posts_pagination()、paginate_links() 等依赖 $wp_query 的函数始终返回空或报错。
✅ 正确做法是：用 WP_Query 替代 get_posts()，显式传递 'paged' => get_query_var('paged')，并确保在循环后调用 wp_reset_postdata() 恢复原始查询状态。
以下是优化后的完整实现示例（已适配你的 HTML 结构）：
<?php global $wp_query;
// 保存原始查询（可选，但强烈推荐用于复杂模板）
$original_query = $wp_query;
$args = array(
'posts_per_page' => 9,
'post_type' => 'post',
'post_status' => 'publish',
'orderby' => 'post_date',
'order' => 'DESC',
// ✅ 关键：获取当前分页参数（支持静态首页、归档页等）
'paged' => get_query_var('paged') ? get_query_var('paged') : 1,
// ⚠️ 注意：避免无必要使用 suppress_filters => true，除非明确需禁用钩子
);
$wp_query = new WP_Query($args);
?>
<div class="row">
<?php if ($wp_query->have_posts()) : ?>
<?php while ($wp_query->have_posts()) : $wp_query->the_post(); ?>
<div class="col-md-4 col-sm-12 mt-3">
<div class="bg-gray h-100 blog-cards">
<a href="<?php%20the_permalink();%20?>" title="بیشتر بخوانید">
<div>
<div class="archive-img">
<?php the_post_thumbnail('medium', array('class' => 'img-fluid')); ?>
</div>
<h3 class="upper mb-0 px-3 pt-3 pb-0 text-dark"><?php the_title(); ?></h3>
<div class="p-3 pt-0">
<?php the_excerpt(); ?><div class="categories mt-2">
<?php $categories = get_the_category();
foreach ($categories as $category) {
echo '<a href="' . esc_url(get_category_link($category->term_id)) . '" class="badge bg-secondary me-1">'
. esc_html($category->name) . '';
}
?>
</div>
<span class="text-muted mt-2 d-block">
مدت زمان مطالعه: <?php echo esc_html(get_field('duration') ?: '۱'); ?> دقیقه
</span>
</div>
</div>
</a>
</div>
</div>
<?php endwhile; ?><!-- ✅ 分页位置：放在循环外，且必须在 wp_reset_postdata() 前 --><div class="col-12 mt-4">
<?php the_posts_pagination(array(
'mid_size' => 2,
'prev_text' => '← قبلی',
'next_text' => 'بعدی →',
'screen_reader_text' => 'نавیگاسیون صفحهبندی'
)); ?>
</div>
<?php else : ?><div class="col-12">
<p class="text-center text-muted py-5">مقالهای یافت نشد.</p>
</div>
<?php endif; ?><?php // ✅ 必须恢复原始 $wp_query，防止影响后续模板（如页脚小工具、相关文章等）
$wp_query = $original_query;
wp_reset_postdata();
?>
</div>
? 重要注意事项：
- 'paged' 参数不可省略：get_query_var('paged') 会自动从 URL（如 /page/2/）或查询字符串（?paged=2）中提取当前页码；若在首页直接访问，需提供默认值 1。
- 避免 suppress_filters => true：除非你确切知道它会屏蔽哪些过滤器（如 posts_where, posts_join），否则建议移除，否则可能破坏 SEO 插件、多语言插件或缓存逻辑。
- wp_reset_postdata() 不等于 wp_reset_query()：前者仅重置全局 $post，适用于 WP_Query；后者重置整个 $wp_query，仅在使用 query_posts()（已废弃）时需要。
- 响应式分页样式：the_posts_pagination() 输出的是语义化
? 扩展提示：若需在首页（home.php）或自定义页面模板中实现分页，且该页面非标准归档页，请确保在 functions.php 中为静态首页启用分页支持：
// functions.php 中添加（仅当首页为 page 而非 posts page 时需要）
function custom_home_pagination_fix($query) {
if (!is_admin() && $query->is_main_query() && is_front_page()) {
$query->set('posts_per_page', 9);
}
}
add_action('pre_get_posts', 'custom_home_pagination_fix');
通过以上调整，你的分页将完全兼容 WordPress 核心机制，并支持 SEO 友好链接、无障碍访问及主题升级维护。
