游标分页常被误解为传统分页的简单变体，实则其底层机制与基于页码的偏移分页截然不同。ThinkPHP框架提供的cursorPaginate()方法，其核心在于通过一个稳定、可比较的“位置标记”来定位数据，而非计算页面偏移量。若未能充分理解这一设计前提，实践中极易遭遇数据重复、记录缺失或分页中断等问题。
ThinkPHP 游标分页的核心前提：必须使用 order 且排序字段不可为 NULL
游标分页的稳定运行，完全依赖于一个绝对可靠的排序字段。ThinkPHP内部会记录上一页最后一条记录的排序字段值，并将其作为下一页查询的起始条件。因此，该排序字段必须满足以下严格条件：值不允许为NULL、需具备唯一性或严格单调性、且能够进行明确的大小比较。
许多开发者遇到的典型问题，例如分页结果莫名跳过部分记录，或从第二页起返回空数据，其根源往往在此。通过查看SQL日志，常会发现生成的WHERE id > '某值'条件未能匹配到任何行。
- 字段非空是基本原则：像自增
id这类主键天然满足条件。若选用create_time等时间字段，则必须确保数据库表字段定义为NOT NULL，且应用层在写入时提供默认值（如当前时间戳），彻底杜绝NULL值的产生。 - 避免使用不确定性排序：诸如
ORDER BY RAND()或ORDER BY ABS(id)这类包含函数的排序方式，会导致“上一页最后一条记录”的位置无法确定，从而使游标机制完全失效。 - 多字段组合排序的注意事项：当使用类似
ORDER BY status ASC, id DESC的组合排序时，游标值也必须是一个包含所有排序字段的数组（例如['status' => 1, 'id' => 100]）。这要求前后端进行更精细的协作，且ThinkPHP 6.1及以上版本对此提供了更完善的原生支持。
ThinkPHP 6.0+ 中 cursorPaginate() 方法的正确调用方式
理解了底层原理后，调用方式便清晰明了。游标分页不再依赖传统的page和limit参数，而是转变为一种依赖“上下文”的连续查询过程。这种模式尤其适配移动端的下拉加载与无限滚动列表，能从根源上规避传统OFFSET在深度分页时产生的严重性能问题。
- 控制器中必须显式声明排序：首先，在模型查询链中必须使用
order方法明确指定排序规则，且此规则需与前端约定的游标字段完全一致。例如：$model->order('id desc')->cursorPaginate(20)。 - 前后端间的游标传递机制：首次请求时，前端可不传或传递空游标参数。ThinkPHP将按排序规则返回第一页数据。关键在于，响应数据中会包含一个
next_cursor字段（注意，这是框架约定的字段名，而非last_id等自定义名称），其值即为获取下一页数据的起点。前端在请求下一页时，需将此next_cursor值作为cursor参数传回后端。 - 返回值结构的正确解析：
cursorPaginate()返回的数据对象中，data属性是当前页的数据列表，而next_cursor属性才是驱动翻页的核心。它是一个数组，其结构取决于order方法中指定的字段数量。
以下是一个简单的正确与错误调用示例对比：
// 正确方式：明确指定排序字段
$list = User::order('id desc')->cursorPaginate(15);
// 错误方式：缺少order，游标分页将失去基准
$list = User::cursorPaginate(15); // 行为不可预测，极易导致错误
使用时间字段进行游标分页需警惕“同一秒内多条记录”的陷阱
使用create_time这类时间戳字段进行游标分页看似合理，却隐藏着一个常见陷阱：在高并发写入场景下，同一秒内产生多条记录的概率很高。如果仅使用WHERE create_time > '上一页最后时间'作为查询条件，则会漏掉同一秒内、但排序在后的其他记录。
更严重的是，这可能导致查询性能退化。数据库为定位数据可能需要进行全表或范围扫描，使得游标分页的性能优势丧失殆尽。
- 采用组合排序是最佳实践：最稳妥的方案是使用组合字段排序，例如
ORDER BY create_time DESC, id DESC。这样，即使时间戳相同，仍可通过id字段保证顺序的唯一性和可精确定位性。 - 提升时间字段的存储精度：对于MySQL 5.6及以上版本，建议使用
DATETIME(3)（毫秒级）或TIMESTAMP(6)（微秒级）类型存储时间，可极大降低时间戳碰撞的概率。 - 谨慎使用更新时间字段：切勿单独使用
update_time作为游标排序字段，因为记录的更新会导致该时间戳变化，破坏其值单调递增的假设，从而引发分页混乱。
自定义游标参数名与兼容旧版 ThinkPHP 的解决方案
ThinkPHP的游标分页默认只识别URL中的cursor查询参数。若你的前端项目已广泛使用after_id或start_id等自定义参数名，直接修改框架源码并非明智之举。
另一个常见误区是，在调用cursorPaginate()之前，试图手动添加where条件来“辅助”定位。这极易与框架内部的游标生成逻辑产生冲突，导致查询结果异常。
- 手动实现游标逻辑：最安全的兼容方式是暂时不使用
cursorPaginate()方法，转而使用基础的where和limit方法手动实现分页逻辑。例如：User::where('id', '<', $lastId)->order('id desc')->limit(20)->select()，然后自行管理并向前端返回下一页的起始ID。 - 请求参数映射方案：若仍希望利用框架封装好的方法，可在控制器入口处进行参数转换。例如，将接收到的
after参数值，通过input助手函数赋值到cursor键上，实现参数名的透明映射。 - 注意框架版本兼容性：需要特别留意，游标分页功能是ThinkPHP 6.0版本引入的。如果你仍在维护ThinkPHP 5.1等旧版本项目，代码中并不存在
cursorPaginate方法，强行调用会导致“方法未定义”的错误。
归根结底，游标分页的复杂性在于其“状态”依赖于上一次查询的结果。这个游标值不仅仅是一个简单的ID数字，它代表了在排序空间中的一个精确坐标。因此，任何环节的错配——无论是排序字段的选择、前后端参数命名的不一致，还是值的数据类型问题——都可能导致分页在静默中失败。此类问题，框架难以做到全自动的容错处理，更需要开发者具备清晰的理解和细致的实践。
