应直接使用KnpPaginatorBundle而非手写分页；安装需三步：composer require、注册bundle、控制器声明Request $request参数；paginate()严格按查询对象、当前页码、每页数量顺序调用；模板中需显式传参且保留非分页参数；大数据量时应禁用totalCount或改用游标分页并确保ORDER BY字段索引且稳定。
直接用 KnpPaginatorBundle，别手写 setFirstResult() 和 setMaxResults() —— 除非你明确只要某一页数据、不关心总页数、也不需要带参数的分页链接。
安装与注册必须做对这三步
漏掉任一环都会报错或分页失效：
- 运行
composer require knplabs/knp-paginator-bundle（注意不是knp_paginator_bundle） - 在
config/bundles.php中添加：Knp\Bundle\PaginatorBundle\KnpPaginatorBundle::class => ['all' => true] - 控制器方法签名里必须声明
Request $request参数，否则paginate()拿不到当前请求，会抛ArgumentCountError
常见错误是跳过第 3 步，只写 $paginator->paginate($query, 1, 10)，结果页面直接 500。
$paginator->paginate() 的参数顺序不能错
它严格要求三个参数：查询对象、当前页码、每页数量。顺序错一个，语义就全乱了：
- ✅ 正确：
$paginator->paginate($query, $request->query->getInt('page', 1), 15) - ❌ 错误：
$paginator->paginate($query, 15, $request->query->getInt('page', 1))→ 分页器把 15 当成页码，首页显示 1 条，第二页显示 2 条…… - 查询对象可以是
Doctrine\ORM\Query、Doctrine\ORM\QueryBuilder或纯 PHP 数组；但别传getScalarResult()或getResult()后的结果，那会把全部数据加载进内存
模板里变量名和参数透传最容易踩坑
{{ knp_pagination_render() }} 不是“自动识别变量”，它默认只找叫 pagination 的变量名：
- 如果控制器返回的是
$users和$orders两个分页对象，必须显式传参：{{ knp_pagination_render(users) }}、{{ knp_pagination_render(orders) }} - 默认只保留
page、sort、direction这几个键；搜索关键词q=foo或状态筛选status=active会被丢掉 - 要保留其他参数，得在
paginate()调用时加第 4 个参数：['q' => 'q', 'status' => 'status']，或者动态构造：array_diff_key($request->query->all(), ['page' => 1])
大数据量时必须干预 totalCount 和排序稳定性
百万级数据下，COUNT(*) + OFFSET 会越来越慢，甚至超时：
- 如果不需要精确总页数（比如只显示“下一页”按钮），加选项：
['totalCount' => false] - 务必确保
ORDER BY字段有索引，且值唯一、稳定（推荐用主键或带索引的createdAt）；否则同时间戳+分页可能漏数据或重复 - 真要遍历全量数据（如导出、通知），改用游标分页：
WHERE id > :lastId ORDER BY id ASC LIMIT 100，放弃跳页能力换性能
最常被忽略的是：没检查 ORDER BY 字段是否真的能保证每次查询顺序一致 —— 这会导致翻页时数据跳跃或重复，而且很难复现。
