ThinkPHP 的 paginate 必须作用于未执行的查询构造器对象，不可用于已执行 select() 返回的 Collection 或数组；正确用法是先构建查询（如 where）、最后调用 paginate()。
ThinkPHP 的
不是“调用一下就自动分页”的黑盒，它本质是基于查询构造器（
）或模型（
）的查询结果做数据切片 + 分页信息封装。直接对已查出的数组调用
会失败——它需要原始查询对象。
为什么
报错？
这是最常踩的坑：
返回的是
（数组对象），而
必须作用于查询构造器实例（即还没执行 SQL 的
对象）。一旦执行了
、
、
等方法，查询就结束了，无法再分页。
✅ 正确：先构建查询，最后一步才调
❌ 错误：把
写在
后面，或对
/
调用
⚠️ 注意：模型静态方法如
是合法的，因为
返回的仍是查询对象
的参数怎么选？常见组合含义
参数顺序和类型直接影响分页行为。ThinkPHP 6+ 默认参数是
，但实际使用中建议显式传参，避免隐式默认值干扰。
：每页条数，整数即可，如
；不要传字符串
（可能触发类型转换异常）
：是否启用简单分页（只含上一页/下一页，不计算总页数），设为
可显著提升大数据量下的性能（跳过
查询）
：关联数组，关键项包括：
（手动指定当前页，避免依赖 URL 参数名）
（分页链接附带的额外 GET 参数）
（URL 中页码参数名，默认是
）
如何在关联查询中正确分页？
模型关联（
、
等）本身不支持直接
，必须转为 JOIN 查询或子查询。否则容易出现“分页条数对不上”或“重复数据”问题。
PHP 8.5.5
PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。
下载
立即学习
“
PHP免费学习笔记（深入）
”；
推荐做法：用
或原生
构建单表查询，再
例如查用户及其部门名称：
避免：
—— 这会先分页查用户，再为每页 N 条用户分别查部门，N 次 SQL，且分页总数不准
如果必须用关联预载入，应先查主表 ID 列表分页，再用
查详情 + 关联，但需自行组装分页对象（较重）
自定义分页模板时，
渲染失败怎么办？
方法依赖模板路径和变量名，不是所有主题都能直接用。默认渲染的是 ThinkPHP 自带的
模板，但项目若覆盖了
配置或用了第三方 UI 框架，就容易出空白或报错。
检查模板是否存在：
（TP6 路径），不存在会静默失败
临时调试：用
输出原始 HTML 字符串，确认分页数据本身没问题
自定义模板时，确保传入的变量名一致：
或
（取决于你 render 时传的键名）
更稳妥的做法：用
直接指定内置样式，比手写模板快且兼容
分页的核心约束始终没变：它必须站在查询未执行的临界点上操作。任何提前求值、数组转换、或忽略查询上下文的操作，都会让
失效。真正难的不是语法，而是时刻意识到——你写的不是“处理数据”，而是在“指挥数据库怎么切数据”。
paginateDbModelpaginate$model->select()->paginate()select()Collectionpaginate()Queryselectfindcountpaginate()paginate()select()arrayCollectionUserModel::where(...)->paginate()wherepaginate()paginate($listRows = 15, $simple = false, $config = [])$listRows10"10"$simpletrueCOUNT(*)$config'page' => input('page/d', 1)'query' => ['status' => 1]'var_page' => 'p'pagehasManybelongsTopaginatewithJoin()join()paginate()UserModel::alias('u')->join('dept d', 'u.dept_id = d.id')->field('u.*, d.name as dept_name')->paginate(10)UserModel::with('dept')->paginate(10)whereIn('id', $ids)$page->render()render()defaulttemplateview/paginate/default.html$page->show(){$page|raw}{$pages|raw}$page->render(['type' => 'bootstrap'])paginate