hyperf 中数据库分页核心是 paginate() 方法，自动处理 limit、offset 和总数统计；支持条件查询、自定义参数、游标分页及前端渲染。
Hyperf 中实现数据库分页很简单，核心是用 paginate() 方法，它会自动处理 LIMIT、OFFSET 和总条数统计。
基础分页写法
在 Model 或 QueryBuilder 中直接调用 paginate()，传入每页数量即可：
-
User::paginate(10)—— 获取用户列表，每页 10 条 -
User::where('status', 1)->paginate(15)—— 带条件的分页 -
DB::table('users')->paginate(12)—— 使用 QueryBuilder 分页
返回结果是 HyperfPaginatorLengthAwarePaginator 实例，包含数据、当前页、总页数、总数等字段。
自定义分页参数
默认从 URL 的 page 参数读取当前页码，也可手动指定：
-
paginate(10, ['*'], 'page', 2)—— 强制第 2 页，第三个参数是查询参数名（可选），第四个是当前页码（可选） - 若想用
offset+limit手动分页，可用forPage($page, $perPage)配合count()自行计算总数
优化大数据量分页性能
当表数据量极大（如千万级），COUNT(*) 可能变慢。可考虑以下方式：
- 用缓存预存总数（适合不频繁变更的数据）
- 改用游标分页（
cursorPaginate()），基于主键或时间戳排序，避免 COUNT 和 OFFSET - 例如：
User::orderBy('id')->cursorPaginate(20)，适用于无限滚动场景
前端渲染与链接生成
分页器自带 render() 方法，返回 HTML 分页控件（兼容 bootstrap 样式）：
-
{{ $users->render() }}在 Blade 中直接输出分页栏 - 如需 json 接口，用
$users->toArray()获取结构化数据，含data、last_page、current_page等字段 - 链接自动适配当前路由和查询参数，无需额外处理
不复杂但容易忽略：确保模型开启 Eloquent 的自动时间戳或主键配置正确，否则 cursorPaginate 可能出错。