KnpPaginatorBundle是Symfony2中实现数据库查询分页最成熟、最稳妥的选择，需严格按三步安装注册、参数顺序调用paginate()、模板显式传参，并在大数据量时禁用totalCount或改用游标分页。

在 Symfony2 中实现数据库查询分页，KnpPaginatorBundle 是最成熟、最稳妥的选择。它不是“可选插件”，而是社区长期验证的事实标准，能自动处理总条数统计、URL 参数继承、排序一致性等手写分页极易出错的环节。

安装与注册三步到位

漏掉任一环节都会导致 500 错误或分页失效：

• 执行 composer require knplabs/knp-paginator-bundle（注意包名无下划线）
• 在 app/AppKernel.php 的 registerBundles() 方法中添加：
  new Knp\Bundle\PaginatorBundle\KnpPaginatorBundle(),
• 控制器方法签名必须声明 Request $request 参数，否则 paginate() 无法读取当前页码，直接报 ArgumentCountError

控制器中调用 paginate() 的关键细节

参数顺序严格固定为：查询对象、当前页码、每页数量。顺序错误会导致逻辑完全错乱：

• ✅ 正确写法：
  $pagination = $paginator->paginate($query, $request->query->getInt('page', 1), 10);
• ❌ 常见错误：
  $paginator->paginate($query, 10, $request->query->getInt('page', 1));
  此时分页器把 10 当作第 1 页，首页显示 1 条，第二页显示 2 条……
• 查询对象支持 QueryBuilder、Query 或数组，但不能传 getResult() 后的结果，否则全量数据进内存

模板渲染必须注意变量名和参数透传

Twig 模板里默认只识别名为 pagination 的变量：

• 若控制器返回 'pagination' => $pagination，模板中直接写：
  {{ knp_pagination_render(pagination) }}
• 若返回多个分页对象（如用户+订单），需分别命名并显式传参：
  {{ knp_pagination_render(users) }}
{{ knp_pagination_render(orders) }}
• 搜索关键词 q=foo、状态筛选 status=active 等非分页参数默认被丢弃
  解决方法：在 paginate() 调用时加第 4 个参数，例如：
  ['q' => $request->query->get('q'), 'status' => $request->query->get('status')]

大数据量场景下的必要优化

当表数据超百万行时，COUNT(*) 会严重拖慢响应：

• 禁用总条数统计：
  $paginator->paginate($query, $page, $limit, ['totalCount' => false]);
• 改用游标分页（推荐）：
  依赖稳定、有索引的排序字段（如 id 或 created_at），避免 OFFSET 性能衰减
• 务必确保 ORDER BY 子句存在且字段已建索引，否则结果可能重复或遗漏