ThinkPHP分页必须作用于未执行的查询构造器对象，不可对已执行select()或all()的结果调用；需显式传参控制page、list_rows及query以保留搜索条件，避免COUNT错误和翻页丢失。
ThinkPHP 的分页在后台管理系统中不是调个 paginate() 就能安稳跑起来的——尤其当表格带搜索、关联字段排序、或需要手动拼接查询条件时，分页容易漏数据、跳页错乱、甚至 SQL 报错。
分页前必须重写查询对象，不能直接 paginate() 原始 Db::table()
很多人习惯写完 Db::table('user')->where(...)->order(...) 就直接链式调用 paginate()，这在简单场景下可行，但一旦涉及 JOIN、GROUP BY 或子查询，ThinkPHP 5.1+ 的 paginate() 会尝试对整个 SQL 自动加 COUNT(*)，而复杂语句常导致 COUNT 失败（比如报错 SQLSTATE[HY000]: General error: 1140 In aggregated query without GROUP BY）。
正确做法是先构建好不含分页的完整查询对象，再传给 paginate()：
$query = Db::table('user')
->alias('u')
->join('dept d', 'u.dept_id = d.id')
->field('u.id,u.name,u.status,d.title as dept_title')
->where('u.status', 'in', [0,1]);
// 搜索条件动态追加
if ($request->param('keyword')) {
$query->where('u.name|u.phone', 'like', "%{$keyword}%");
}
// 注意：这里不调用 paginate()，只保留 $query 对象
$list = $query->paginate(15, false, ['query' => request()->param()]);
- 务必用变量保存查询对象，避免链式调用后丢失上下文
-
paginate(15, false, [...])第二个参数false表示不自动重构 SQL，改由框架基于主键（默认id）做游标式 COUNT，更稳定 -
['query' => request()->param()]是为了让分页链接保留当前搜索参数，否则翻页后搜索条件丢失
关联模型分页时，避免 with() 导致 count 错误
用 UserModel::with('dept') 分页，ThinkPHP 默认会对 with 关联的表也参与 COUNT，但关联表字段不在主表 SELECT 中时，COUNT 语句可能因 JOIN 产生重复行，导致总条数虚高（比如一个部门有 5 个用户，COUNT(*) 算出 5 行，但加上 with('dept') 后，如果 dept 表字段被拉取，COUNT 可能误算成 5 × 部门数）。
立即学习“PHP免费学习笔记（深入）”；
安全做法是显式控制 COUNT 范围：
$list = UserModel::withoutField('dept.*') // 排除关联字段干扰 COUNT
->with(['dept' => function($q) {
$q->field('id,title'); // 关联查字段要精简
}])
->where('status', 1)
->paginate(15);
- 不要依赖
with()自动处理分页，它不感知 COUNT 上下文 -
withoutField()不影响最终数据展示，只屏蔽字段参与 COUNT 构建 - 关联模型里务必用
field()限制返回字段，否则 N+1 问题会放大分页内存开销
自定义分页参数名和 URL 格式，适配 Vue/React 前端
后台管理常用 Ajax 加载表格，但 ThinkPHP 默认分页生成的是 ?page=2 这类 GET 参数，前端若用 axios.get('/admin/user/list', { params: { page: 2 } })，服务端接收不到 page——因为 paginate() 默认从 $_GET['page'] 读，而框架路由可能已关闭 GET 参数解析（如用了 url_common 或伪静态）。
解决方法是统一入口参数，并透传给分页器：
$page = (int)input('get.page/d', 1);
$limit = (int)input('get.limit/d', 15);
$list = Db::table('user')->where(...)->paginate([
'list_rows' => $limit,
'page' => $page,
'var_page' => 'page', // 显式指定参数名，和前端对齐
'query' => ['limit' => $limit], // 保证下一页链接带 limit
]);
-
input('get.page/d', 1)比直接用$_GET安全，且支持类型强制转换 -
var_page必须设为'page'，否则前端传page=2，后端按$_GET['p']去读就失效 - 如果前端用
/api/user?page=2&limit=20这种路径，记得在路由配置里放开get_allow或禁用参数过滤
分页最麻烦的从来不是显示页码，而是「什么时候该重算总数」「哪些字段不能进 COUNT」「关联查询如何不拖慢 LIMIT OFFSET」——这些细节藏在 paginate() 底层的 SQL 生成逻辑里，不看执行日志、不抓实际 SQL，很容易线上出错才发觉。
