在 Symfony 7.0 中为 Doctrine 查询结果添加分页必须使用 KnpPaginatorBundle，需安装依赖、在 bundles.php 中注册、控制器显式注入 Request 并按序传入查询对象/页码/每页数，模板中变量名须为 pagination 且直接遍历，大数据量时可禁用 totalCount 或优化排序索引。
在 Symfony 7.0 中为 Doctrine 查询结果添加分页功能，必须使用 KnpPaginatorBundle 而非手写 offset/limit 逻辑，否则将丢失请求上下文、参数透传和模板渲染能力，页面直接报 ArgumentCountError 或分页链接失效。
安装与注册 Bundle
运行命令安装依赖：composer require knplabs/knp-paginator-bundle。注意包名是 knplabs/knp-paginator-bundle，不是旧版的 knp_paginator_bundle 或 knp-components。
打开 config/bundles.php，添加一行：Knp\Bundle\PaginatorBundle\KnpPaginatorBundle::class => ['all' => true]。漏掉这行会导致服务容器找不到 knp_paginator 服务，控制器中 $this->get('knp_paginator') 报错或自动注入失败。
无需手动配置 services.yaml，Bundle 已内置默认服务定义；也不需要修改 Kernel 或 AppKernel —— Symfony 7 已废弃传统 bundle 注册方式，bundles.php 是唯一有效入口。
控制器中调用 paginate()
在控制器方法签名中必须显式声明 Request $request 参数，例如：public function listAction(Request $request): Response。这是 Symfony 7.0+ 的硬性要求，隐式注入或省略该参数会导致 paginate() 无法读取 page 查询参数，抛出 ArgumentCountError。
获取查询构建器后，调用 paginate() 时严格按顺序传入三个参数：查询对象、当前页码、每页数量。例如：$pagination = $paginator->paginate($qb, $request->query->getInt('page', 1), 12)。
⚠️ 错误示例：$paginator->paginate($qb, 12, $request->query->getInt('page', 1)) → 分页器把 12 当作页码，第一页显示 1 条，第二页显示 2 条……完全错乱。顺序不可交换。
查询对象推荐传 QueryBuilder 或 Query，不要传 $qb->getQuery()->getResult()——那会把全量数据加载进内存，失去数据库层分页意义。
模板中正确渲染分页
在 Twig 模板里，{{ knp_pagination_render(pagination) }} 这行代码能生效的前提是：控制器返回的变量名必须叫 pagination。如果返回的是 users 和 posts 两个分页对象，必须分别写：{{ knp_pagination_render(users) }} 和 {{ knp_pagination_render(posts) }}。
分页链接默认只保留 page、sort、direction 三个查询参数。若当前 URL 是 /admin/users?q=john&status=active&page=3，点击“下一页”后会变成 /admin/users?page=4，q 和 status 全丢。
要保留其他参数，需在控制器中 paginate() 调用时传第 4 个参数：['q' => 'q', 'status' => 'status']。更健壮的做法是动态提取：array_diff_key($request->query->all(), ['page' => 1])，避免漏配键名。
遍历数据时直接用 {% for user in pagination %}，不要写 pagination.items 或 pagination.data —— Symfony 7.0 的 KnpPaginatorBundle 返回的是 PaginationInterface 实例，它实现了 Traversable，原生支持 for 循环。
大数据量优化（可选但强烈建议）
方法一：关闭 totalCount 计算
当数据表超 50 万行时，COUNT(*) + LIMIT/OFFSET 会严重拖慢响应。在 paginate() 第 4 参数中加入 'totalCount' => false，例如：$paginator->paginate($qb, $page, 12, ['totalCount' => false])。此时 pagination.totalItemCount 为 null，模板中不能用 {{ pagination.totalItemCount }}，但 {{ knp_pagination_render() }} 仍可生成“下一页”按钮。
方法二：确保 ORDER BY 字段有数据库索引且值稳定
如果排序字段含 NULL、或存在大量重复值（如 status 字段只有 active/inactive），OFFSET 分页会出现跳行或重复。必须为 ORDER BY created_at, id 这类组合添加联合索引，并在查询中显式写出：$qb->addOrderBy('u.createdAt')->addOrderBy('u.id')。
