KnpPaginatorBundle分页报错主因是未传$request参数，需在Controller中显式声明并传入paginate()；默认丢弃非分页查询参数，应通过第4参数透传；大数据量时建议关闭totalCount或改用游标分页；Twig中须用pagination.currentPageNumber等正确属性名。
分页器初始化时报 ArgumentCountError：Controller 里没传 $request
Knplabs/KnpPaginatorBundle 的 KnpPaginatorInterface::paginate() 必须拿到当前请求对象才能解析 page、sort、direction 这些参数。漏传 $request 是最常见报错原因。
实操建议：
- Controller 方法签名里显式声明
Request $request参数（Symfony 5.4+ 支持自动注入，但别依赖隐式行为） - 调用
paginate()时第 3 个参数必须是$request，不能是空数组或null - 如果用的是 Symfony 6.3+ 的新式控制器（
#[AsController]），仍需在方法参数中写明Request $request
典型错误示例：$pagination = $paginator->paginate($queryBuilder, 1, 10); → 缺少 $request，会直接崩。
分页链接生成后全是 /page/2，不带原有查询参数
默认情况下，KnpPaginatorBundle 只保留 page、sort、direction，其他 GET 参数（比如搜索关键词 q=foo、筛选状态 status=active）会被丢掉 —— 这不是 bug，是默认行为。
实操建议：
- 在
paginate()调用时传入第 4 个参数：['page' => 'page', 'sort' => 'sort', 'direction' => 'direction', 'q' => 'q', 'status' => 'status']，把需要透传的键名列出来 - 更稳妥的做法是动态收集：
$request->query->all()拿全部，再 unset 掉page等分页专用键，避免漏配 - 注意：路由必须支持 query string，别用
path()生成纯路径而丢弃$request->getQueryString()
用 Query 或 QueryBuilder 分页时内存暴涨或超时
Knplabs 默认对 Doctrine 查询做 COUNT + LIMIT/OFFSET，但当表数据量大、COUNT 慢、或关联太多时，OFFSET 本身就会变慢（MySQL 尤其明显），还可能触发全表扫描。
实操建议：
- 确认是否真需要精确总页数：如果只是“下一页”，可设
['totalCount' => false]关闭 COUNT，前端显示“查看更多”而非“第 32 页” - 用游标分页替代：改用主键/时间戳做条件（如
id > 12345），性能稳定，但需放弃跳页功能 - 给
COUNT加索引：确保WHERE条件字段有复合索引，避免 COUNT 走全表 - 避免在
paginate()前手动getQuery()->getResult()，这会让整个结果集加载进内存
模板里渲染分页时，pagination 对象属性名容易写错
Twig 中访问分页数据不是用 pagination.totalItemCount 这类直觉命名，而是遵循 Bundle 自己的契约接口，写错就渲染为空或报错。
实操建议：
- 翻文档不如看源码：实际可用的属性是
pagination.currentPageNumber、pagination.itemNumberPerPage、pagination.totalItemCount、pagination.hasNextPage、pagination.hasPreviousPage - 别写
pagination.totalPages（不存在），要用(pagination.totalItemCount / pagination.itemNumberPerPage)|round(0, 'ceil') - 判断是否有数据：用
pagination|length > 0，别用pagination.items|length，因为items是懒加载代理，长度可能不准
最常被忽略的一点：分页器返回的 items 是数组还是 Collection，取决于你传进去的是 Query 还是数组 —— 传 QueryBuilder 返回 ArrayCollection，传数组返回原生数组，遍历时 for 循环写法一样，但调试时 var_dump 类型容易懵。
