WordPress源码深度解析之：`WordPress`的`WP_Query`：`posts_per_page`与`paged`参数的底层逻辑。

WordPress WP_Query：posts_per_page 与 paged 参数的底层逻辑探秘

各位好！今天咱们来聊聊 WordPress 中一个非常核心的类 —— WP_Query。特别是它里面的两个好兄弟：posts_per_page 和 paged。 这两个参数是分页查询的关键，看似简单，实则背后隐藏着不少逻辑。我保证，听完这次分享，你就能彻底搞懂它们，以后在 WordPress 里玩转分页，那绝对是信手拈来！

1. WP_Query 简介：查询界的“瑞士军刀”

WP_Query 就像 WordPress 查询界的“瑞士军刀”，几乎所有的数据查询都离不开它。你想获取文章、页面、自定义文章类型，甚至用户、评论，都可以通过它来实现。而 posts_per_page 和 paged，就是这把瑞士军刀上负责“分页”的关键部件。

2. posts_per_page：一次性展示多少篇文章？

posts_per_page 参数顾名思义，就是指定每页要显示的文章数量。如果你设置 posts_per_page 为 10，那么每次查询（在特定页面上）都会最多返回 10 篇文章。

2.1. 默认值和设置方法

posts_per_page 默认值是由 WordPress 后台的“设置 -> 阅读”中设置的“文章显示数量”决定的。当然，你也可以在 WP_Query 中显式地指定它：

$args = array(
    'posts_per_page' => 5, // 每页显示 5 篇文章
);

$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        // 显示文章内容
        the_title();
        the_content();
    }
    wp_reset_postdata(); // 恢复全局 $post 对象
} else {
    echo '没有文章';
}

2.2. -1 的特殊含义

如果将 posts_per_page 设置为 -1，那就像给查询引擎开了个“无限模式”，它会一次性返回所有符合条件的文章。这在某些特定场景下非常有用，比如生成站点地图、导出所有文章等。但需要注意的是，如果你的文章数量巨大，一次性加载所有文章可能会导致服务器压力过大，甚至崩溃。所以，慎用！

3. paged：我要看第几页？

paged 参数用于指定要显示的页码。如果你想看第二页的文章，就可以设置 paged 为 2。

3.1. 获取当前页码

在 WordPress 中，当前页码通常是从 URL 中获取的。WordPress 会自动解析 URL 中的 paged 参数，并将其传递给 WP_Query。

• 主循环： 在主循环（比如博客首页、分类页面、标签页面）中，paged 参数会自动被设置。你无需手动处理。
• 自定义查询： 在自定义查询中，你需要手动获取 paged 参数。通常可以使用 get_query_var( 'paged' ) 函数来获取：

$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1; // 获取当前页码，如果未设置则默认为 1

$args = array(
    'posts_per_page' => 10,
    'paged'          => $paged,
);

$query = new WP_Query( $args );

// ... (显示文章的代码)

3.2. get_query_var('page') 与 get_query_var('paged') 的区别

你可能会注意到，除了 paged，还有一个 page 参数。它们之间有什么区别呢？

• page：用于静态页面的分页。当你在一个页面中使用 <!--nextpage--> 分页符时，WordPress 会使用 page 参数来控制分页。
• paged：用于文章列表的分页。比如博客首页、分类页面、标签页面、搜索结果页面等。

简单来说，page 用于页面内容分页，paged 用于文章列表分页。

4. 底层逻辑：WP_Query 如何处理 posts_per_page 和 paged？

现在，让我们深入 WP_Query 的源码，看看它是如何处理这两个参数的。

4.1. parse_query() 方法：参数解析

WP_Query 的核心方法之一是 parse_query()。这个方法负责解析传递给 WP_Query 的参数，并将它们转换为 SQL 查询语句。

// 源码位置：wp-includes/class-wp-query.php

public function parse_query( $query = '' ) {
    // ... (省略部分代码)

    // 默认值
    $this->query_vars = array_merge( $this->query_vars, wp_parse_args( $this->query ) );

    // 设置 posts_per_page 的默认值
    if ( ! isset( $this->query_vars['posts_per_page'] ) || '' === $this->query_vars['posts_per_page'] ) {
        $this->query_vars['posts_per_page'] = get_option( 'posts_per_page' );
    }

    // 确保 posts_per_page 是一个整数
    $this->query_vars['posts_per_page'] = absint( $this->query_vars['posts_per_page'] );
    if ( $this->query_vars['posts_per_page'] == 0 ) {
        $this->query_vars['posts_per_page'] = 1;
    }

    // 处理 paged 参数
    if ( ! isset( $this->query_vars['paged'] ) || ! $this->query_vars['paged'] ) {
        if ( get_query_var( 'paged' ) ) {
            $this->query_vars['paged'] = absint( get_query_var( 'paged' ) );
        } elseif ( get_query_var( 'page' ) ) {
            $this->query_vars['paged'] = absint( get_query_var( 'page' ) );
        } else {
            $this->query_vars['paged'] = 1;
        }
    }

    // 确保 paged 是一个整数
    $this->query_vars['paged'] = absint( $this->query_vars['paged'] );

    // ... (省略部分代码)
}

这段代码做了以下几件事：

1. 合并参数： 将传递给 WP_Query 的参数与默认参数合并。
2. 设置 posts_per_page 默认值： 如果没有显式设置 posts_per_page，则从 WordPress 设置中读取。
3. 确保 posts_per_page 是整数： 使用 absint() 函数将 posts_per_page 转换为绝对整数，并确保其值不为 0。
4. 处理 paged 参数： 如果没有显式设置 paged，则尝试从 get_query_var( 'paged' ) 或 get_query_var( 'page' ) 中获取。如果都没有，则默认为 1。
5. 确保 paged 是整数： 使用 absint() 函数将 paged 转换为绝对整数。

4.2. get_posts() 方法：构建 SQL 查询

get_posts() 方法负责构建实际的 SQL 查询语句。它会根据 posts_per_page 和 paged 参数，生成 LIMIT 和 OFFSET 子句，从而实现分页查询。

// 源码位置：wp-includes/class-wp-query.php

public function get_posts() {
    // ... (省略部分代码)

    // 计算 OFFSET
    if ( ! empty( $this->query_vars['offset'] ) ) {
        $offset = absint( $this->query_vars['offset'] );
    } else {
        $offset = absint( ( $this->query_vars['paged'] - 1 ) * $this->query_vars['posts_per_page'] );
    }

    // 构建 LIMIT 子句
    $limits = 'LIMIT ' . $offset . ', ' . absint( $this->query_vars['posts_per_page'] );

    // ... (省略部分代码)

    $this->request = apply_filters( 'posts_request', $this->request, $this );

    // 执行查询
    $this->posts = $wpdb->get_results( $this->request );

    // ... (省略部分代码)
}

这段代码的关键在于计算 OFFSET 和构建 LIMIT 子句：

• 计算 OFFSET： OFFSET 指的是从结果集的哪个位置开始返回数据。它通过以下公式计算：

  OFFSET = (当前页码 - 1) * 每页文章数

  例如，如果 paged 为 2，posts_per_page 为 10，那么 OFFSET 就是 (2 – 1) * 10 = 10。这意味着从结果集的第 11 篇文章开始返回数据。

• 构建 LIMIT 子句： LIMIT 子句用于限制返回结果的数量。它包含两个参数：OFFSET 和 每页文章数。例如：

  LIMIT 10, 10

  这表示从结果集的第 11 篇文章开始，返回 10 篇文章。

4.3 代码示例

为了更清晰地理解这个过程，让我们看一个具体的例子。假设我们有 25 篇文章，posts_per_page 设置为 10，paged 设置为 2。

1. parse_query() 方法： 会将 posts_per_page 设置为 10，paged 设置为 2。
2. get_posts() 方法： 会计算 OFFSET：(2 – 1) * 10 = 10。然后构建 LIMIT 子句：LIMIT 10, 10。

3. SQL 查询： 最终生成的 SQL 查询语句可能类似于：

   SELECT * FROM wp_posts WHERE post_type = 'post' AND post_status = 'publish' ORDER BY post_date DESC LIMIT 10, 10

   这条 SQL 语句会从 wp_posts 表中选择 post_type 为 post 且 post_status 为 publish 的文章，按照 post_date 降序排列，然后从第 11 篇文章开始，返回 10 篇文章。

5. 分页导航：让用户轻松翻页

仅仅实现分页查询还不够，我们还需要提供分页导航，让用户可以方便地切换到不同的页面。WordPress 提供了 paginate_links() 函数，可以自动生成分页导航链接。

$total_pages = $query->max_num_pages; // 获取总页数

if ( $total_pages > 1 ) {
    $current_page = max( 1, get_query_var( 'paged' ) );

    echo paginate_links( array(
        'base'      => get_pagenum_link( 1 ) . '%_%',
        'format'    => '/page/%#%',
        'current'   => $current_page,
        'total'     => $total_pages,
        'prev_text' => __('« 上一页'),
        'next_text' => __('下一页 »'),
    ) );
}

这段代码做了以下几件事：

1. 获取总页数： 使用 $query->max_num_pages 获取总页数。
2. 获取当前页码： 使用 get_query_var( 'paged' ) 获取当前页码。
3. 生成分页导航链接： 使用 paginate_links() 函数生成分页导航链接。

paginate_links() 函数接受一个数组作为参数，用于配置分页导航的各个方面：

• base：分页链接的基础 URL。
• format：分页链接的格式。%#% 会被替换为页码。
• current：当前页码。
• total：总页数。
• prev_text：上一页链接的文本。
• next_text：下一页链接的文本。

6. 性能优化：让分页飞起来

分页查询虽然方便，但如果处理不当，可能会影响网站的性能。以下是一些性能优化的建议：

• 避免过度使用 posts_per_page = -1： 如前所述，一次性加载所有文章可能会导致服务器压力过大。
• 使用缓存： 将查询结果缓存起来，可以避免重复查询数据库。可以使用 WordPress 的 Transients API 或其他缓存插件。
• 优化数据库查询： 确保数据库表上有适当的索引，可以加快查询速度。
• 使用 pre_get_posts 钩子： pre_get_posts 钩子允许你在 WP_Query 执行之前修改查询参数。这可以让你在全局范围内修改分页行为，而无需修改每个查询。

7. 总结：posts_per_page 和 paged 的“最佳拍档”

posts_per_page 和 paged 是 WP_Query 中用于分页查询的两个关键参数。它们共同决定了每页显示的文章数量和要显示的页码。理解它们的底层逻辑，可以帮助你更好地控制 WordPress 的分页行为，并优化网站的性能。

参数	作用	默认值
posts_per_page	每页显示的文章数量	WordPress 后台“设置 -> 阅读”中设置的“文章显示数量”
paged	要显示的页码	如果 URL 中包含 paged 或 page 参数，则从 URL 中获取；否则默认为 1
offset	从结果集的哪个位置开始返回数据(优先级高于paged)	如果没有显式设置，则使用公式 (当前页码 - 1) * 每页文章数 计算

掌握了这两个参数，你就可以轻松地在 WordPress 中实现各种复杂的分页需求。记住，posts_per_page 负责 “量”，paged 负责 “页”，它们是名副其实的 “最佳拍档”！

好了，今天的分享就到这里。希望对大家有所帮助！下次再见！