WordPress中$paged变量官方文档缺失的原因及相关疑问

问题背景 #

作为WordPress新手，在阅读前辈编写的首页index.php代码时，遇到了未在官方文档全局变量列表中找到的$paged变量，相关代码如下：

<?php
$i = 0;
if ( have_posts() ) : while ( have_posts() ) : the_post();
{
    if ($i == 0 && $paged < 1)
    {
        show_content("","12","card", "4");
    }
    elseif ($paged >= 1) { get_template_part( 'template-parts/content', 'card' ); }
    $i = $i + 1;
}
endwhile; else:
    echo("<p>No post found :(<p>");
endif;
?>

疑问点：该变量是否已过时？为何未被官方收录？使用是否存在问题？

核心解答 #

• $paged并未过时
  $paged是WordPress中负责处理归档类页面（首页、博客列表、分类/标签归档等）分页的全局变量，至今仍被大量主题、插件和自定义代码使用，属于当前有效且常用的变量。

• 官方文档未单独收录的原因
  WordPress官方对全局变量的文档整理较为分散，$paged这类变量通常不会作为单独条目出现在全局变量列表中，而是在分页相关函数（如paginate_links()、WP_Query参数说明）的文档中被提及。此外，$paged是WordPress核心运行时自动初始化的“隐性”全局变量，依赖URL中的paged参数赋值，这类变量的文档往往隐藏在具体功能的说明里，新手直接搜索全局变量列表容易遗漏。

• 使用$paged的注意事项
  正常使用无问题，但需留意两个细节：

  1. $paged的默认值为0，对应分页的第一页，这也是代码中判断$paged < 1的逻辑依据；
  2. 自定义WP_Query时，需手动传递paged参数，否则自定义查询的分页会失效，示例代码：

     $custom_query = new WP_Query(array(
         'paged' => get_query_var('paged') ?: 1
     ));
     

  另外，代码中$paged < 1的判断可以替换为WordPress提供的语义化函数!is_paged()，能提升代码可读性。

内容的提问来源于stack exchange，提问作者Hải Đăng