游标分页必须用唯一单调字段（如id）排序，且select需包含该字段；禁用withCount、groupBy等破坏查询结构的操作；按name分页须加orderBy('id')二级排序。
如果您在 Laravel 中尝试使用游标分页但结果出现重复、遗漏或静默失败，则很可能是游标排序字段选择不当或查询构造违反了 cursorPaginate() 的底层约束。以下是正确使用 Laravel cursor 分页的关键操作步骤：
一、确保排序字段唯一且单调递增
游标分页依赖上一页末尾记录的排序字段值精确定位下一页起点，因此该字段必须满足两个硬性条件：全局唯一（无重复值）与严格单调（值只增不减）。若使用非唯一字段（如 created_at 在高并发下易重复）或非单调字段（如 updated_at 可能回退），将导致 WHERE 条件无法锚定唯一位置，从而跳过或重复加载数据。
1、优先选用 自增主键 id 作为排序字段，它天然满足唯一性与单调性。
2、若需按时间语义分页，必须组合 created_at 和 id，即 orderBy('created_at')->orderBy('id')，确保时间相同时仍可由 id 精确区分顺序。
3、避免单独使用 name、status、updated_at、score 等字段，它们或重复率高、或更新不可控、或业务逻辑上不保证递增。
二、正确调用 cursorPaginate() 方法
cursorPaginate() 不是 paginate() 的简单替代，其执行依赖于纯净的 ORDER BY + WHERE + LIMIT 查询结构，任何破坏该结构的操作都会导致游标失效或 SQL 报错。它不会自动补全被 select() 过滤掉的游标字段，也不会兼容聚合、分组或复杂关联。
1、基础用法必须包含 显式 orderBy() 且字段保留在 select 列表中，例如：User::where('active', true)->orderBy('id')->cursorPaginate(20)。
2、若使用 select()，必须 显式包含游标字段（如 id），否则 WHERE 条件因缺失列而报错，正确写法为：select('id', 'name', 'email')。
3、禁止在 cursorPaginate() 前调用 withCount()、groupBy()、distinct() 或复杂 join，这些操作会干扰 COUNT(*) 或游标定位逻辑，引发 Column not found 或空结果集。
三、处理非标准查询场景的替代方案
当业务强制要求按非单调字段（如 name）分页，或需对接原始 SQL、第三方数据源时，原生 cursorPaginate() 不再适用，需改用可控性更强的手动游标逻辑或降级方案。
1、对 name 分页，必须添加二级排序：使用 orderBy('name')->orderBy('id')，确保 name 相同的记录仍可通过 id 唯一锚定。
2、若查询来自 DB::select() 或 API 聚合数据，先按游标字段预排序并缓存全量索引，再通过 array_filter() 或二分查找模拟游标偏移，手动切片返回。
3、在必须使用 updated_at 的场景下，需在模型事件中强制同步更新逻辑，确保每次变更都触发 updated_at = NOW() ON UPDATE CURRENT_TIMESTAMP 且禁止手动赋值回退时间。
四、验证游标行为与调试技巧
Laravel 不提供游标值解码接口，实际游标是 Base64 编码的 JSON 字符串，内含上一页末尾记录的排序字段值。调试重点在于确认生成的 SQL 是否符合游标语义，而非解析游标本身。
1、启用 DB::enableQueryLog() 并在 cursorPaginate() 后调用 DB::getQueryLog()，检查生成的 SQL 是否含 WHERE 排序字段 > ? 及正确的 LIMIT。
2、在控制器中临时添加日志：打印 $users->nextCursor()->encode()，对比前后两次请求的游标字符串是否随数据推进而变化。
3、使用 tinker 手动执行游标 SQL：取上一页最后一条记录的 id 值，执行 SELECT * FROM users WHERE id > 123 ORDER BY id LIMIT 20，结果应与 cursorPaginate() 完全一致。
