ThinkPHP前后端分离分页必须用paginate()而非limit()+count()，因其自动统一统计总数与数据查询、校验页码边界、封装标准元信息；需手动解构返回扁平化JSON结构（如list/total/pageSize等字段），并显式处理前端自定义参数名以避免翻页失效。
ThinkPHP 的分页接口在前后端分离场景下，必须返回标准、可预测的 JSON 结构，不能依赖模板渲染或内置分页 HTML —— 否则前端拿不到 total、last_page 或 current_page 这类关键字段，Vue/React 分页组件（如 Element Plus 的 el-pagination 或 Ant Design 的 Pagination）会直接失效。
tp5/tp6/tp8 中必须用 paginate() 而非 limit() 手动分页
手动 limit() + count() 虽然可控，但容易漏掉总条数计算逻辑、忽略排序一致性、无法自动适配不同数据库的偏移语法。而 paginate() 内置了：总数统计（带相同 where/order）、当前页数据切片、页码边界校验、以及关键元信息封装。
-
paginate($size)会自动读取请求中的page参数（默认为 1），无需手动$request->param('page', 1) - 返回对象包含
total、per_page、current_page、last_page、has_pages等字段，结构稳定，前端可直接解构 - 若需自定义 page 参数名（比如前端传的是
pageNum），得配合Page::setPageName('pageNum')（tp6+）或重写 Request 对象（tp5） - 注意：tp5 默认返回的是
Collection包裹的数组；tp6/tp8 返回的是Paginator实例，调用toArray()才能转成纯数组供json()输出
后端响应结构必须扁平化，避免嵌套过深
ThinkPHP paginate() 默认返回的数据在 data.data 里，而前端框架通常期望列表直接在 data.list 或 data.items 下。硬套默认结构会导致 Vue 模板写成 v-for="item in data.data"，既难读又易错。
- 正确做法是手动解构再组装：
$paginated = $query->paginate($size); return json([ 'code' => 200, 'msg' => 'success', 'data' => [ 'list' => $paginated->items(), 'total' => $paginated->total(), 'page' => $paginated->currentPage(), 'pageSize' => $paginated->listRows(), 'pages' => $paginated->lastPage(), ] ]); - 不要用
$paginated->toArray()直接返回——它会把data作为 key 嵌套一层，且字段名（如per_page）和前端常用命名（如pageSize）不一致 - 如果项目统一用 RESTful 风格，建议固定字段名为
items、pagination两级结构，便于 axios 响应拦截器统一处理
前端传参不规范会导致 paginate() 读错页码或大小
paginate() 默认只认 page 和 page_size（tp6+ 支持配置），但 Vue/React 组件常传 pageNum、pageSize、current、size 等变体。参数名不匹配时，ThinkPHP 会回退到默认值（通常是 page=1, size=15），导致「翻页无效」或「始终显示第一页」。
立即学习“PHP免费学习笔记（深入）”；
- 最稳妥方式：在控制器里显式取参，不依赖
paginate()自动解析$page = (int) $request->param('pageNum', 1); $pageSize = (int) $request->param('pageSize', 10); $list = $query->paginate(['list_rows' => $pageSize, 'page' => $page]); - tp6+ 可通过
think\facade\Paginator::config(['var_page' => 'pageNum', 'var_page_size' => 'pageSize'])全局覆盖，但要注意中间件执行顺序，避免被其他模块重置 - 别在 URL 里混用 query 和 path 参数传分页信息（如
/api/users/1表示 page=1），paginate()不解析 path 参数
真正容易被忽略的点是：分页元信息（如 total）必须和数据查询在同一个事务或同一时刻快照中获取。如果先查总数、再查数据，中间有写入，就可能造成「显示有 100 条，实际只返回 99 条数据」——尤其在高并发后台管理场景。tp 的 paginate() 内部用子查询或缓存 count，已规避该问题，但自己手写 count() + limit() 就得加事务或 for update 锁。
