很多项目里，PageIndex这个词一冒出来，大家第一反应就是“分页嘛，第几页而已”。可真正动手做的时候你就会发现，一个看似简单的页码，往深了牵扯到接口参数约定、数据库查询性能、前端状态管理，甚至并发环境下的数据一致性。我接过不少带搜索列表、评论列表、操作日志列表的项目，几乎每个里面都有 PageIndex 的身影，但实现水平差距很大。有的项目数据量只有几百条时一切正常，一旦涨到几十万条，页面就卡到让人怀疑人生；有的项目分页参数定义混乱，打开第 5 页返回的数据和界面上显示的总页数对不上。这篇内容就把 PageIndex 从参数定义、计算公式、数据库优化到前端交互完整梳理一遍，给正在写列表功能或者准备做分页工具的同学一个可以直接落地的参考。

1. 先弄清楚：PageIndex 在不同语境里是什么

1.1 接口请求参数里的页码

最常用的语境就是 Web 接口和前端页面里的“页码”。你可能已经注意到，不同团队的接口文档里，第 2 页的传法五花八门，有的是page=2，有的是pageIndex=2，还有的用p=2。虽然名字不一样，它们表达的概念都叫 PageIndex，只是不同语言习惯下保留了不同的命名。

这个参数通常配合pageSize（也叫limit、size）一起出现，含义就是“我要第几页、每页多少条”。比如请求：

GET /api/orders?pageIndex=2&pageSize=20

有些人会认为这是第 2 页，有些人会认为这是第 3 页，因为有一批项目使用 0 作为第一页索引。这个细节看起来很小，但一旦前端和后端对不上，就会出现“我点了第 5 页，结果重新加载后列表数据跳到第 6 页”的怪毛病。后面我专门讲从 0 开始和从 1 开始的取舍。

1.2 存储引擎里的页索引

把视角拉到数据库和文件系统层面，PageIndex 又变成了完全不同的东西。在 InnoDB 这类存储引擎中，数据是按“页”（Page）存储的，每页通常是 16KB。B+ 树叶子节点按主键顺序组织，页内又有行记录的槽位（slot）。这里的 page index 可以理解成“某个数据页在表空间中的位置”，或者“页内某条记录所在的位置编号”。

为什么一个做业务开发的人也要关心这个？因为分页参数最终要翻译成 SQL 里的OFFSET和LIMIT。OFFSET其实不是数据库里精确记录的“页号”，它只是一种“跳过多少行”的指令。数据库引擎为了找到跳过的那些行，得沿着 B+ 树索引一路扫描，扫描过程中就会经过很多物理数据页。所以，pageIndex这个业务概念，在数据库底层是这样一步步转换成“读取哪些页、跳过哪些行”的物理操作的。

1.3 为什么两层含义都要理解

如果你只把 PageIndex 当作前端组件里的一个数字，那出了问题的时候，你会觉得“数据不对就在接口层查一下”，很难想到问题的根源可能出在存储引擎扫描了多少页、走了什么索引。

举个例子，同样都是“第 100000 页”，在 API 层看来只是一个整数，在 SQL 优化器眼里却意味着可能要扫描前两百万条记录再扔掉，然后才返回你真正要的 20 条。这个认知差异，直接影响系统的吞吐量和响应时间。

所以我建议做列表功能的同学，脑子里同时保留两套模型：上层叫页码索引，是业务概念；下层叫页扫描偏移量，是存储概念。两套模型打通之后，你再去看分页慢的问题，思路会清晰很多。

2. Web 分页的核心公式与边界处理

2.1 从 0 开始还是从 1 开始

这个老生常谈的问题，实际项目里真的要逼前后端统一。Elasticsearch 和很多编程语言里的数组下标天然从 0 开始，所以内部 API 用 0 作为第一页的很多。而 UI 上用户看到的页码通常从 1 开始，产品经理写需求也习惯写“第 1 页”。

我的建议是：对外展示页号用 1 基底，内部接口参数统一用 0 基底。后端接口收到前端传来的pageIndex时，如果前端传的是页面显示页码，就在前端先转成 0 基底再发请求；如果后端要直接面向产品或者第三方开放，那就明确写在文档里，并给出转换示例。

0 基底和 1 基底换算公式很简单：

// 0 基底 offset = pageIndex * pageSize // 1 基底 offset = (pageIndex - 1) * pageSize

关键是全过程只用一种，不要出现“后端用 0，前端用 1，然后前端又在 URL 里偷偷减 1”的双重换算。这种别扭的兼容我最怕遇到，排查问题时非常容易绕晕。

2.2 页码到偏移量的换算

假设你已经确定了接口从 0 开始接收 pageIndex，那么核心公式就四组：

offset = pageIndex * pageSize totalPages = ceil(totalCount / pageSize) currentPageCount = min(pageSize, totalCount - offset) emptyPage = offset >= totalCount

比如总记录数 105 条，pageSize=20，pageIndex=4：

offset = 4 * 20 = 80 totalPages = ceil(105 / 20) = 6 currentPageCount = min(20, 105 - 80) = 20

这表示第 5 页应该有 20 条数据。当 pageIndex=5 时：

offset = 5 * 20 = 100 currentPageCount = min(20, 105 - 100) = 5

所以最后一页只有 5 条。这种情况下，如果前端把页码显示到第 7 页，那后端返回的数据就应该是空数组，而不是把超出范围的请求硬拗到最后一页。

2.3 边界条件和空结果的坑

分页最容易翻车的不是正常页数，而是边界。我总结过几个必测场景：

第一，totalCount = 0时总页数怎么处理？数据库层算出来是 0，但是页面上肯定不能显示“第 0 页 / 共 0 页”。我的做法是接口里返回totalPages = Math.max(1, Math.ceil(totalCount / pageSize))，让前端至少有一页空列表可以展示，同时提供“暂无数据”的 UI 状态。

第二，用户删除数据后，如果刚好把最后一页的数据删光了，那原来的“最后一页”就变成空页。此时前端拿到空列表，不能直接停在空页上，而应该基于响应里的totalPages做一次纠偏。比如原来的 pageIndex=9，现在总页数只有 8，那就要把页码重新设回 8 再请求一次。我倾向于前端做这个纠偏，后端不做偷偷改 pageIndex 的逻辑，因为后端不知道用户当前操作意图。

第三，pageSize 为 0 或者负数。很多接口如果传pageSize=0，SQL 会直接报错或者返回奇怪结果。参数校验阶段就要拦截掉。

第四，超大 pageIndex。比如 pageIndex=99999999，如果不对参数做限制，数据库可能真的会去执行一个深度偏移的查询，然后长时间占用连接。常规做法是设置 pageSize 上限，比如最多 100，同时允许 pageIndex 很大，但要接受空结果和性能损失。再严格一点，可以限制最大 offset，比如超过 100000 就提示用筛选条件缩小范围。

3. 数据库侧的 PageIndex：分页背后的执行原理与性能陷阱

3.1 OFFSET 分页的真实执行过程

很多开发者以为OFFSET只是“跳过前面 N 行”的廉价操作，其实完全不是。看这条 SQL：

SELECT id, order_no, amount FROM orders WHERE status = 1 ORDER BY id DESC LIMIT 20 OFFSET 100000;

数据库执行的时候，需要先根据status和排序条件找到符合条件的记录集合，然后从第一条开始数，数够 100000 条后再丢到一边，最后才把第 100001 到第 100020 行返回给客户端。也就是说，OFFSET 越大，数据库实际扫描和排序的中间行数就越多，但真正返回给你的只有 20 条。

用EXPLAIN看执行计划，经常会看到rows的值是 100020 左右，这还只是估算。如果排序字段没有索引，还会触发文件排序（filesort），把符合条件的记录全部先放到排序缓冲区，数据量大时甚至要落盘到临时文件，性能直接归零。

这里有个很反直觉的点：明明用户翻页是线性前进的，数据库工作量却随着页数增大而线性堆积。第 1 页可能只需要扫 20 行，第 5000 页就要扫 10 万行，所以很多系统都会出现“前几页很快，越往后越卡”的现象。

3.2 深分页为什么慢

深分页慢的本质原因，可以归结为三点：

一是无效扫描。OFFSET 跳过的行本身对最终结果毫无意义，但数据库必须逐行检查，尤其是遇到 WHERE 条件过滤时，可能扫描 10 行只有 1 行符合条件，那么实际扫描量更大。

二是排序成本。如果ORDER BY的字段没有索引，或者排序条件与 WHERE 条件组合不出合适索引，数据库就得把所有符合 WHERE 条件的记录都收集起来排序。翻页越深，参与排序的记录越多，内存排序变成磁盘排序，耗时陡增。

三是回表代价。即使排序字段有索引，如果查询的列不在索引里，数据库还得根据主键回表拿完整行数据。OFFSET 越大，回表次数越多，IO 压力自然越大。

曾经我维护过一个监控系统，告警日志表有几百万条数据。后台的“历史告警”列表一开始用 OFFSET 分页，刚开始上线时还好，一个月后用户往后翻几页就转圈圈。最后定位到就是典型的深分页问题，解决办法是改成了游标式分页。

3.3 键集分页和它的适用场景

解决深分页问题，业界比较成熟的方案叫“键集分页”，也叫 Seek Method、keyset pagination、cursor pagination。核心思想是：不告诉数据库要跳过多少行，而是告诉它“从哪一行开始取”。

拿上面的 SQL 举例，改成这样：

SELECT id, order_no, amount FROM orders WHERE status = 1 AND id < :lastSeenId ORDER BY id DESC LIMIT 20;

这里lastSeenId是上一页最后一条记录的 ID，前端把它们当作“下一页游标”传给后端，后端把它放进 WHERE 条件。数据库直接通过主键索引定位到这个 ID 的位置，然后从它后面继续取 20 条。因为不再需要跳过大量行，所以无论翻到第 5000 页还是第 5 万页，性能都基本恒定。

键集分页最大的特点就是不能跳页。用户想看第 50 页，你没法在不知道第 49 页最后一条记录的情况下直接定位。所以它更适合“加载更多”这种无限滚动场景，以及信息流、聊天记录这类天然按时间倒序浏览的内容。

如果你的业务要求同时支持传统页码跳转，又要应对超大偏移量，可以做个折中：默认前 1000 页以内允许 OFFSET 跳页，超过之后只允许按时间范围或游标继续翻。这个阈值可以根据实际性能测试去定，并没有统一标准。

下面我把两种方式对比一下，方便按场景选型：

使用键集分页时有一个关键点：排序条件里必须有一个全局唯一且单调递增的字段，最常见的就是主键 ID。如果排序条件经常变，比如按创建时间、按价格、按状态，那你要确保 WHERE 条件里的游标字段和 ORDER BY 字段是同一个复合索引的一部分，否则索引也帮不上忙。

4. 设计稳定的 PageIndex 语义：totalPages、跳页与一致性

4.1 totalPages 的正确计算

接口返回体里，除了当前列表数据，通常还应该带上这组字段：

{ "list": [], "pageIndex": 2, "pageSize": 20, "totalCount": 105, "totalPages": 6 }

注意totalPages是一个计算值，不是数据库存下来的字段。正确算法是：

totalPages = Math.ceil(totalCount / pageSize)

这里有一个容易踩的坑：totalCount查询和当前列表查询不是同一个时刻执行的，如果两次请求之间正好有数据插入或删除，就可能出现“totalPages 显示 6，但翻到第 6 页时数据不足 20 条”的情况。这本身不算错误，但前端要做兜底，拿到的 list 数量小于 pageSize 且页号等于 totalPages 时，不要继续加载。

我在实际项目里还会遇到 totalCount 被缓存的情况。为了性能，有些团队会把 count 查询结果缓存一分钟，但列表查询不缓存，这就导致页面上显示的总页数和列表实际数据错位。如果系统对一致性要求比较高，我建议 count 和 list 的数据源尽量保持一致，至少不要一个查了近实时数据，一个查了分钟级缓存。

4.2 数据变化导致页面上跳怎么办

这个场景在信息流、帖子列表、评论区特别常见。用户看到第 5 页，这时候有人在前面新增了一条数据，原来的第 5 页就变成了第 6 页的内容。用户继续翻页时，会发现某几条数据被重复看到了，或者中间感觉“跳了一下”。

这不是 PageIndex 本身算错了，而是基于“固定偏移量”的分页语义天然无法解决动态数据问题。因为你用 OFFSET 定义页面位置，前面多一条，后面全部跟着变。

要缓解这个问题，有几个思路：

一种是把分页改成“加载更多 + 游标”模式，其实从产品层面规避了位置漂移。用户看到哪条，就以那条为锚点往后拉，新插入的数据只会出现在列表顶部，不会干扰已经加载的区域。

另一种是保留 PageIndex 模式，但要求列表排序必须稳定。比如先用唯一 ID 降序做最终排序，时间相同的数据也有稳定的先后顺序。这样即使前面新增了记录，重复或跳过的概率也会低一些。

最忌讳的是排序里出现完全随机或不确定的因子。我见过有人用ORDER BY RAND()做列表排序，那 PageIndex 分页基本就只剩个摆设了，来回翻页数据全乱。

4.3 跳页缓存和页码纠偏策略

为了减少后端压力，列表页通常会做缓存。缓存 key 一般长这样：

list:{module}:{filters}:{pageIndex}:{pageSize}

把 filters 和分页参数一起拼进 key，可以保证不同筛选条件下的数据不会串。比如用户先按状态过滤，再切换状态查询，如果缓存 key 里漏了状态值，那第二页返回的第一页数据，排查下来就很容易浪费时间。

缓存过期策略也很重要。分页结果不是永久不变的，通常用写操作触发失效。我比较推荐“版本号 + 缓存”组合：每次表格数据发生写入时版本号加 1，读取时把版本号和 pageIndex 一起作为 key 的一部分，这样旧缓存自动过期，新查询自然命中新数据。

页码纠偏指的是前端拿到响应后，根据 totalPages 调整当前高亮页。比如用户在第 9 页，刷新后数据被删掉一部分，totalPages 变成了 5，前端就必须把显示页码改回 5。好的做法是给分页组件加一个“受控页号”状态，列表数据到达后主动 sync 一次，不要让页号停在超出范围的数字上。

5. 一套可落地的 PageIndex 分页实战

5.1 后端接口参数设计与校验

假设你的后端使用 Python，我用一个接近真实项目的代码结构来说明。首先定义分页请求对象：

from dataclasses import dataclass @dataclass class PageRequest: page_index: int = 0 # 从 0 开始 page_size: int = 20 def __post_init__(self): if self.page_index < 0: self.page_index = 0 if self.page_size < 1: self.page_size = 20 # 限制单页最大条数，防止恶意传参 if self.page_size > 100: self.page_size = 100 @property def offset(self) -> int: return self.page_index * self.page_size

这个类把参数校验和偏移量计算都封装进去了。接口层只要接收两个参数，就能保证后续 SQL 使用到的limit和offset不会出现负数或超大值。

我习惯在调用数据库查询之前打印一条调试日志：

SELECT orders where status=1 order by id desc limit 20 offset 100

线上出问题的时候，这行日志能帮你快速复现到底是哪一页哪一批数据出了问题。

5.2 SQL 层和映射层实现细节

有了 PageRequest，SQL 层的查询逻辑就比较清晰了：

def query_orders(db, condition, page_req): # 总数查询 total_count = db.select("COUNT(*)").from_("orders").where(condition).scalar() # 当前页数据 items = ( db.select("*") .from_("orders") .where(condition) .order_by("id DESC") .limit(page_req.page_size) .offset(page_req.offset) .fetchall() ) total_pages = max(1, math.ceil(total_count / page_req.page_size)) return { "list": items, "pageIndex": page_req.page_index, "pageSize": page_req.page_size, "totalCount": total_count, "totalPages": total_pages, }

这段代码里有两个细节值得注意。第一，ORDER BY尽量不要直接用前端传过来的字段名，而是定义一个白名单映射。如果前端可以把任何列名放进排序字段，SQL 注入的风险和索引失效的风险都会增加。第二，COUNT(*)在没有 WHERE 条件下有时会很慢，但高并发场景下如果不做缓存，一次分页查询会产生两次 DB 交互，压力翻倍。我通常会把 count 和 list 放到同一个事务里，或者至少保证它们使用的数据源一致。

5.3 前端列表状态与页码组件联动

前端拿到的 pageIndex 和页码组件之间，需要一套清晰的状态管理逻辑。我用 React 的例子来说明：

const [pageIndex, setPageIndex] = useState(0); const [pageSize, setPageSize] = useState(20); const [filters, setFilters] = useState({ status: 1 }); const [pageData, setPageData] = useState({ list: [], totalPages: 0, totalCount: 0 });

请求函数里，把 pageIndex、pageSize、filters 拼成查询参数：

async function fetchList() { const params = new URLSearchParams({ pageIndex: pageIndex, pageSize: pageSize, status: filters.status, }); const resp = await fetch(`/api/orders?${params.toString()}`); const data = await resp.json(); setPageData(data); // 如果当前页码已经超出总页数，自动纠偏 if (pageIndex > data.totalPages - 1) { setPageIndex(Math.max(0, data.totalPages - 1)); } }

注意，这里纠偏之后还需要再触发一次请求，否则页面会停留在空列表状态。一个常见的写法是使用 useEffect 监听 pageIndex 和 filters 的变化，但要注意防止死循环。我的建议是：纠偏时先判断是否真的越界，越界才 setPageIndex，不越界就不动，避免每次响应都触发一次额外请求。

筛选条件变化时，pageIndex 一定要重置为 0。很多人会忘记这一步，导致用户切换筛选条件后，还停在原来的第三页，而第三页可能已经是空数据或者别的筛选条件下的错位数据。下面这个逻辑要写成惯例：

useEffect(() => { setPageIndex(0); }, [JSON.stringify(filters)]);

6. 高频问题排查实录与经验速查

6.1 典型现象和排查方向

做分页功能这一路，我整理了一张高频问题表，发现问题先对着这个方向查，能省下大量时间：

6.2 我踩过的坑和心得

我第一次认真审视分页参数时，发现自己亲手写过一个非常丑的兼容逻辑：后端要求 pageIndex 从 1 开始，前端组件从 0 开始，于是前端请求接口时又加了个+1。本来这个还能跑通，后来另一个后端接口把规范改了，从 0 开始，前端代码没同步，结果一个页面上两个列表，一个正常一个错位，排查了整整半天。从此我立了一个规矩：接口层一定要强制统一基底，谁也甭想偷偷换算。

还有一次处理一个百万量级的数据导出功能，产品经理希望“导出所有筛选后的数据”，我一开始图省事，直接用 pageIndex 循环拉全量。结果跑到第 2000 页时，每页响应时间从 300ms 涨到了 3 秒，整个导出流程跑了快一小时。后来改成直接按 ID 区间分批扫描，效率才恢复正常。这个经历让我意识到，分页不仅能用来做屏幕展示，也能被误用在数据导出和批处理上，但后者用 keyset 方式明显更合适。

参数校验这件事，我也吃过亏。有人传了一个pageIndex=-1来测试接口，当时后端没校验，SQL 直接生成了负 offset，数据库报错暴露在响应体里，不仅难看，还泄露了表结构信息。从那以后，分页请求对象上的校验我从来不省，哪怕简单到只有三行。

最后再分享一个容易忽略的细节：分页接口的响应体里，最好把pageIndex和pageSize原样返回。这样前端做状态同步时，可以直接拿接口返回值覆盖本地状态，避免因中间层参数转换导致的分歧。我自己现在做接口设计，都会把这条当成默认约定。分页这件小事，做扎实了，列表功能基本就稳了一半。