KNP Paginator生成分页URL不匹配路由规则问题排查

KNP Paginator 默认使用page作为页码参数名、默认将分页参数追加到URL查询字符串（query string）中。生成分页链接时组件会自动检测当前路由是否存在和分页参数同名的路径参数：如果找不到同名路径参数，就会把分页参数放到?后面的查询段，这就是你看到链接变成/asset-search?page=5的核心原因——你的路由定义里的路径参数名是offset，和组件默认的page参数名不匹配，组件找不到对应路径占位符，就自动把参数塞到查询参数里了。

另外你的逻辑里还存在参数语义不匹配的问题：路由里定义的offset是数据偏移量（从0开始计数），但KNP Paginator的分页参数是页码（从1开始计数），二者语义不一致后续很容易出现分页计算错误。

优先用改造成本最低、逻辑最清晰的方案：调整路由参数名匹配KNP的默认规则，不需要额外修改组件配置。

1. 修改控制器路由注解和参数定义，把offset路径参数改成page，默认值设为1（对应第一页，等价于原来offset=0的逻辑）
2. 调用paginate()方法时直接传入$page作为当前页码，不需要额外做1 + $offset的计算
3. Twig模板的渲染逻辑不需要改动

修改后的控制器代码示例：

/**
 * @param int      $limit
 * @param int      $page
 * @param \Symfony\Component\HttpFoundation\Request $request
 *
 * @Route("/asset-search/{page<\d+>?1}/{limit<\d+>?24}", name="asset_search")
 *
 * @return Response
 */
public function searchAssets(Request $request, PaginatorInterface $paginator, int $page = 1, int $limit = 24): Response
{ 

    // ..... 保留你原有的API调用、提取资产ID、查询资产实体的逻辑

    /* @var PaginatorInterface $paginatedSearchResults */

    // 配置分页，直接传入$page作为当前页码即可
    $paginatedSearchResults = $paginator->paginate($assets, $page, $limit);
    $paginatedSearchResults->setTotalItemCount($jsonResponse->total);
    $paginatedSearchResults->setCustomParameters([$filters]);
    $totalResultCount = $paginatedSearchResults->getTotalItemCount();

    // 剩下的模板返回逻辑保持不变
}

改完之后分页组件会自动识别路由里的page和limit路径参数，生成符合你预期的/asset-search/5/24格式的链接，Twig模板不需要做任何修改。

如果你一定要保留offset作为路径参数名，需要手动修改KNP分页的参数名配置，但是要注意offset是偏移量、KNP用的是页码，二者逻辑需要手动转换，很容易出bug：

$paginatedSearchResults = $paginator->paginate(
    $assets,
    (int)($offset / $limit) + 1, // 手动把偏移量转成页码
    $limit,
    [
        'pageParameterName' => 'offset' // 把分页参数名改成和路由里的offset一致
    ]
);

这种方式需要你自己处理所有页码和偏移量的转换逻辑，后续维护成本高，不建议使用。

内容的提问来源于stack exchange，提问作者Richard Bridge