WordPress 经典主题分页功能完全指南

发布于 作者:

导读：分页是 WordPress 主题开发中绕不开的功能模块。无论你是搭建博客、新闻站还是企业官网，当文章列表超过单页承载量时，分页就决定了用户能否顺畅地浏览内容。本文基于 WordPress 官方文档，系统讲解经典主题下四种分页场景的实现方法：文章列表分页、数字分页导航、单篇文章上下篇、以及长文内部分页。我会把 Loop、$wp_query、<!--nextpage--> 这些概念拆开讲清楚，并附上可直接套用的代码示例。读完这篇，你应该能应对大部分主题的分页需求。

一、分页是什么？WordPress 在哪儿用到它？

分页就是把内容切分成多个页面。WordPress 在两种情况下会用到分页：

  1. 文章列表分页：博客首页、分类页、归档页、搜索页等，当文章数量超过后台设置的每页显示数（默认 10 篇）时，自动切分成多页。这个数量可以在 仪表盘 > 设置 > 阅读 里调整。
  2. 单篇文章内部分页：编辑文章时手动插入 <!--nextpage--> 标签，把一篇长文拆成多页。常见于长篇教程或连载内容。

注意：本文讨论的是「经典主题」的分页方式，对应 WordPress 使用 functions.php 和 PHP 模板文件的传统开发模式。区块主题（FSE）的分页逻辑有所不同。

二、准备知识：理解 Loop 和 $wp_query

在动手写分页代码之前，先弄清楚两个概念：

Loop（循环）：WordPress 用来输出文章列表的核心流程。简单说就是：查数据库 → 有文章就一条条显示 → 没文章就提示「没有内容」。

$wp_query 全局对象：它保存了当前页面的查询结果。比如你打开分类页，$wp_query 里就存着这个分类下的所有文章数据。分页函数需要读取 $wp_query 才知道总共有多少页、当前在几页。

如果你要在模板文件（比如 header.php）的非主循环位置调用分页函数，必须先声明 global $wp_query; 让函数能访问到查询数据。在主循环内部调用则不需要。

三、文章列表分页（常用）

这是日常开发中频繁使用的分页形式。

基础示例：在主循环前后放置分页链接

下面这段代码展示了分页函数在模板中的典型位置——放在 Loop 之前和之后各放一组，用户翻到页面底部不用再滚回顶部找翻页按钮。

php

<?php if ( have_posts() ) : ?>

    <!-- 在循环之前：显示上一页/下一页链接 -->
    <div class="nav-previous alignleft">
        <?php next_posts_link( '更早的文章' ); ?>
    </div>
    <div class="nav-next alignright">
        <?php previous_posts_link( '较新的文章' ); ?>
    </div>

    <!-- 主循环开始 -->
    <?php while ( have_posts() ) : the_post(); ?>
        <!-- 这里输出文章标题、摘要、缩略图等内容 -->
        <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
    <?php endwhile; ?>
    <!-- 主循环结束 -->

    <!-- 循环之后：再次放置相同的分页链接 -->
    <div class="nav-previous alignleft">
        <?php next_posts_link( '更早的文章' ); ?>
    </div>
    <div class="nav-next alignright">
        <?php previous_posts_link( '较新的文章' ); ?>
    </div>

<?php else : ?>
    <p><?php _e( '抱歉，没有找到符合条件的文章。' ); ?></p>
<?php endif; ?>

三种常用列表分页函数

1. posts_nav_link()——简单，一行代码生成「上一页」和「下一页」链接，适合对样式要求不高的主题。

php

posts_nav_link();

2. next_posts_link() 和 previous_posts_link()——分别控制「下一页」和「上一页」的显示与链接文字，灵活性更高。

php

next_posts_link( '加载更多' );
previous_posts_link( '返回' );

3. 获取链接用于变量存储——如果需要在 PHP 逻辑中处理分页链接，用 get_next_posts_link() 和 get_previous_posts_link()。

php

$next_link = get_next_posts_link( '下一页' );
$prev_link = get_previous_posts_link( '上一页' );

注意：next_posts_link() 在列表页显示的是「更早的文章」，因为文章列表按发布时间倒序排列，越往后翻时间越早。「上一页」和「下一页」的语义容易混淆，建议用「较新/更早」来命名链接文字。

四、数字分页导航（推荐）

当文章总页数很多时（比如几十上百页），只显示「上一页/下一页」用户体验很差。数字分页能让用户直接跳转到任意页码。

WordPress 4.1+ 推荐方案：the_posts_pagination()

这个函数直接输出一套完整的分页导航，包含页码数字、上一页和下一页箭头，并且自带响应式。

php

the_posts_pagination( array(
    'mid_size'  => 2,      // 当前页前后各显示几个页码
    'prev_text' => '← 上一页',
    'next_text' => '下一页 →',
) );

兼容旧版方案：paginate_links()

如果你的主题需要兼容 WordPress 4.1 以下版本，用 paginate_links() 配合 echo 输出。

php

echo paginate_links( array(
    'total'     => $wp_query->max_num_pages,
    'current'   => max( 1, get_query_var( 'paged' ) ),
    'mid_size'  => 2,
    'prev_text' => '←',
    'next_text' => '→',
) );

注意：在非主循环模板中使用 paginate_links() 时，一定要先声明 global $wp_query;，否则函数不知道总页数。

五、单篇文章的上下篇导航

文章列表分页处理的是「多篇文章的列表」，而单篇文章（single.php）的导航是另一回事——它连接的是「上一篇发布的文章」和「下一篇发布的文章」。

在 single.php 模板的 Loop 内部使用这两个函数：

php

<?php while ( have_posts() ) : the_post(); ?>
    <!-- 文章正文 -->
    <?php the_content(); ?>
    
    <!-- 单篇文章上下导航 -->
    <div class="nav-single">
        <div class="nav-previous">
            <?php previous_post_link( '%link', '← %title' ); ?>
        </div>
        <div class="nav-next">
            <?php next_post_link( '%link', '%title →' ); ?>
        </div>
    </div>
<?php endwhile; ?>

%link 和 %title 是占位符，分别生成链接标签和文章标题。你也可以只传文字：

php

previous_post_link( '上一篇', '上一篇' );
next_post_link( '下一篇', '下一篇' );

六、文章内部分页（长文拆分）

如果你在写一篇超长教程，希望把它分成多个页面，在编辑器的「文本」模式下插入 <!--nextpage--> 标签即可。

但仅插入标签还不够——主题模板需要用 wp_link_pages() 在前端显示页码切换入口。

在 single.php 的 Loop 中，放在 the_content() 之后：

php

<?php while ( have_posts() ) : the_post(); ?>
    <!-- 输出正文，<--nextpage--> 在这里被解析 -->
    <?php the_content(); ?>
    
    <!-- 文章内部分页导航 -->
    <?php wp_link_pages( array(
        'before' => '<div class="page-links">' . __( '页面：' ),
        'after'  => '</div>',
        'link_before' => '<span>',
        'link_after'  => '</span>',
    ) ); ?>
<?php endwhile; ?>

wp_link_pages() 会生成类似「页面：1 2 3 4」的数字列表，点击即可在不同段落间跳转。

七、总结

应用场景核心函数模板文件备注
文章列表分页next_posts_link() / previous_posts_link()index.php, archive.php, category.php 等放在 Loop 前后
数字分页导航the_posts_pagination() 或 paginate_links()同上推荐使用数字导航
单篇文章上下篇next_post_link() / previous_post_link()single.php放在 Loop 内部
文章内部分页wp_link_pages()single.php配合 <!--nextpage--> 标签使用

分页是主题开发的基础能力，但细节并不少。列表分页和单篇导航用的是不同的函数族，内部导航又有独立的标签和函数，新人容易混淆。记住一个判断逻辑：看你在什么页面——在文章列表页用列表分页函数，在单篇文章页用单篇导航函数，需要数字页码就用 paginate_links() 系函数。

把这套逻辑理清楚，WordPress 主题分页这块就不会再卡住了。