CakePHP分页链接丢失参数的根本原因是Paginator助手默认只识别page参数，不自动透传其他GET参数；需在控制器中用getQueryParams()提取并过滤空值和page，再通过url选项显式传入各分页方法。
为什么 CakePHP 的 paginator 生成的分页链接总丢参数？
根本原因不是模板写错了，而是 paginator 助手默认只认 page 参数，其他查询参数（比如 ?category=tech&sort=desc）压根不自动透传。你点“下一页”，URL 就变成纯 ?page=2，筛选条件全丢——这不是 bug，是 CakePHP 的默认行为：它不主动保留非分页上下文的参数。
常见错误现象包括：?page=2 后搜索关键词消失、状态筛选重置、中文参数变乱码、甚至因空值拼接导致 ?keyword=&status= 这类无效 URL。
- 别依赖
$this->Paginator->options(['url' => $this->request->getQuery()])—— 它会把所有 query 值原样塞进链接，但没过滤空值或敏感字段 - 手动拼 URL 时漏了
urlencode()，尤其含中文或特殊符号时，直接触发 404 - 在 AJAX 分页场景下，用
$this->request->getParsedBody()替代getQuery()，结果拿不到 GET 参数
怎么让 paginator 正确拼上 category、sort 等非 page 参数？
CakePHP 4.4+ 起，PaginatorHelper::numbers()、prev()、next() 等方法都支持 url 选项，但必须显式传入干净的参数数组，不能靠框架自动推断。
推荐做法是在控制器里统一提取并清洗参数，再注入视图：
立即学习“PHP免费学习笔记（深入）”；
- 在控制器中用
$this->request->getQueryParams()拿全部 GET 参数，再用array_filter()去掉空值：$cleanParams = array_filter($this->request->getQueryParams(), function($v) { return $v !== null && $v !== ''; }); - 确保
page不参与透传（否则会重复出现），用unset($cleanParams['page'])显式剔除 - 在视图中调用时传入：
$this->Paginator->prev('«', ['url' => $cleanParams])、$this->Paginator->numbers(['url' => $cleanParams]) - 如果用了路由前缀（如
/admin/），需额外加'_full' => true或提前配置Router::setRequest($this->request)，否则链接路径错位
page 参数名能改成 p 吗？改完后链接 404 怎么办？
可以改，但必须前后端同步，只改模板里的链接名是无效的。CakePHP 的分页逻辑在控制器层就已绑定 page，若 URL 传 ?p=2，$this->paginate() 根本收不到，始终按第 1 页查数据，自然 404 或空白。
正确改法分两步：
- 在控制器中显式指定参数名：
$this->paginate = ['paramType' => 'querystring', 'pageParam' => 'p'];（CakePHP 4.4+ 支持） - 同时确保视图里所有
paginator方法都带['page' => 'p']选项，例如：$this->Paginator->numbers(['page' => 'p', 'url' => $cleanParams]) - 注意：旧版 CakePHP（如 3.x）不支持
pageParam，只能靠中间件重写请求参数，或统一用Router::connect('/list/*', [...], ['routeClass' => 'InflectedRoute'])配合自定义解析
分页总数算错、最后一页空白，是不是 paginator 自己的问题？
不是。CakePHP 的 paginator 只负责渲染，总数计算完全取决于控制器里 $this->paginate() 执行时的查询条件是否与 COUNT 查询严格一致。常见崩坏点是：列表查了 WHERE status = 1 AND category_id = 5，但 COUNT 却是全表统计，导致页码多出几页，点进去查不到数据。
修复关键就一条：COUNT 和数据查询必须共用同一套条件链。
- 别在
$this->paginate()之后补where()，比如：$query->where(...)->paginate(); $query->where(...);—— 后者不影响分页总数 - 用
$this->paginate($query)形式，确保传入的是已完整构建的 Query 对象 - 如果用了自定义 finder（如
find('published')），确认该 finder 内部没有隐式修改 WHERE 条件，否则 COUNT 会漏条件 - 删数据后务必刷新分页对象，不要复用旧的
$this->Paginator->counter()结果，它不会自动感知数据变更
最易被忽略的是：当使用 contain() 关联查询时，COUNT 默认不走 JOIN，可能少算——此时得手动用 $query->select(['count' => $query->func()->count('*')])->leftJoin(...) 重写计数逻辑。
