原生 SQL 在 ThinkPHP 中无法直接用 paginate()，因其仅支持 Query 构造器（如 Db::name() 或模型），而 Db::query() 返回纯数组，无链式调用能力，强行调用会报“Call to undefined method paginate()”错误。
原生 SQL 在 ThinkPHP 中无法直接用 paginate()，必须手动处理总数、偏移量和分页对象组装——这是最常被忽略的前提。
为什么不能直接对 Db::query() 调用 paginate()
因为 paginate() 是 Query 构造器方法，只作用于 Db::name() 或模型实例；Db::query() 返回的是纯数组，没有链式能力，也没法自动推导 COUNT。强行套用会报错：Call to undefined method think\db\Connection::paginate()。
常见错误现象：
- 写成
Db::query("SELECT * FROM user")->paginate(10)—— 语法错误，直接 Fatal Error - 只查数据不查总数，前端渲染页码时
$page->lastPage为 0 或空 - offset 计算错位（比如没减 1），导致第一页漏数据或重复
Page 类手动组装分页对象的实操要点
ThinkPHP 5/6 都支持 think\Paginator\driver\Page 手动构造，但参数顺序和字段名容易踩坑。
立即学习“PHP免费学习笔记（深入）”；
关键步骤：
- 用
input('page', 1)获取当前页，别用input('page') ?: 1—— 空字符串会被当 0，导致 offset 为负 - 总数查询必须用
Db::query("SELECT COUNT(*) AS tp_count FROM ...")，取值用$count_data[0]['tp_count']（TP5 默认字段名是count(*)，但带括号在某些 PDO 模式下会出错，显式别名更稳） - 构造
Page对象时，第 4 个参数是总数，不是布尔值；第 5 个参数是是否简单分页（设false才有首页/尾页） - URL 参数要透传：用
['query' => request()->param()]，否则自定义参数（如搜索关键词）在翻页时丢失
示例片段：
php
$page = input('page', 1);
$limit = 15;
$count = Db::query("SELECT COUNT(*) AS tp_count FROM user WHERE status = 1")[0]['tp_count'];
$list = Db::query("SELECT id,name FROM user WHERE status = 1 LIMIT " . ($page - 1) * $limit . "," . $limit);
<p>$paginater = \think\Paginator\driver\Page::make($list, $limit, $page, $count, false, [
'path' => \think\facade\Url::build('user/index'),
'query' => request()->param()
]);
$this->assign('list', $list);
$this->assign('page', $paginater->render());</p>复杂查询（JOIN / GROUP BY）下 COUNT 的写法陷阱
原生 SQL 分页最麻烦的不是 LIMIT，而是怎么写一个等价的 COUNT 查询——尤其当主查询含 GROUP BY 或多表 JOIN 时，直接套 COUNT(*) 会错算行数。
正确做法：
- 如果主查询是
SELECT u.id, u.name, COUNT(o.id) FROM user u LEFT JOIN order o ON u.id = o.user_id GROUP BY u.id，COUNT 必须用子查询：SELECT COUNT(*) FROM (SELECT u.id FROM user u LEFT JOIN order o ON u.id = o.user_id GROUP BY u.id) AS tp_count_sub - 避免在 COUNT 查询里写
SELECT COUNT(*) FROM (原始SQL) AS t—— TP5.1+ 对子查询 COUNT 支持不稳定，容易报Unknown column - 用
Db::execute()执行 COUNT 更安全，返回整数而非数组，省去取键操作
分页 HTML 渲染后样式错乱或链接失效
手动构造的 Page 对象默认用框架内置模板，但路径、参数或 URL 生成逻辑不对时，render() 输出的链接可能指向错误路由或缺参。
排查重点：
- 检查
path配置是否为完整 URL（如/admin/user/index），不是相对路径或空字符串 - 确认
request()->param()是否包含非分页参数（如keyword=abc），否则翻页后搜索条件丢失 - 如果用了路由绑定，
Url::build()必须传入对应路由名，不能只写控制器/方法字符串 - 自定义分页模板需放在
view/page/下并命名为default.html，否则render()不会加载
真正难的从来不是写几行 SQL，而是让总数、偏移、URL、模板四者严丝合缝——少一个环节，用户点“下一页”就 404 或回到第一页。
