paginate()返回lengthawarepaginator实例而非数组，前端需取response.data.data获取数据；simplepaginate()跳过count(*)提升性能，但无total/last_page；api响应应手动构造json结构统一字段名。
直接用 paginate() 就能分页，但返回结构不是数组，前端取不到数据是常态，不是你代码写错了。
为什么 paginate() 返回的数据前端遍历不了
它返回的是 LengthAwarePaginator 实例，不是纯数组。这个对象里真正要渲染的数据藏在 data 字段下（API 响应）或通过遍历本身获取（Blade 模板），但字段名、嵌套层级和前端预期往往不一致。
- API 场景：后端
return $users->paginate(10)，前端收到的是类似{ "data": [...], "links": {...}, "meta": {...} }的结构，必须读response.data.data才是用户列表 - Blade 场景：可直接
@foreach($users as $user)，因为LengthAwarePaginator实现了IteratorAggregate；但$users->total()才是总条数，不是count($users) - 常见错误：把整个
LengthAwarePaginator对象丢给前端 JSON 序列化，导致字段名不统一（如per_page而非pageSize）、next_page_url为null（实际是nextPageUrl）
paginate() 和 simplePaginate() 到底选哪个
核心区别就一条：是否执行 COUNT(*) 查询。这直接影响性能和字段可用性。
-
paginate(15)：查总数 + 当前页数据，返回完整元信息（last_page、total、nextPageUrl、prevPageUrl），适合后台列表、带页码跳转的场景 -
simplePaginate(15)：只查limit + 1条，判断是否有下一页，返回hasMorePages和nextPageUrl（注意驼峰命名），无total或last_page，适合“加载更多”或无限滚动 - 千万级表没索引时，
paginate()的COUNT很可能超时；simplePaginate()却不会——但必须显式orderBy('id')，否则 MySQL 8+ 下结果可能错乱或重复
搜索参数怎么保留在分页链接里
默认分页链接只带 page，其他如 ?keyword=abc&status=active 全丢。不处理，点第二页就回到全部数据。
- Laravel 9+ 推荐用
->withQueryString()：自动携带当前请求所有 query 参数，一行解决 - Laravel 8.x 或需过滤参数时，用
->appends(['keyword' => request('keyword'), 'status' => request('status')]) - 别在
appends()里传敏感字段（如token、api_key），也别传空值（appends(['q' => null])会生成?q=） - 手动构造分页器（如调第三方 API 后分页）时，
appends()不生效，得在LengthAwarePaginator构造参数里显式传['query' => request()->except('page')]
API 响应里怎么让分页字段名统一可控
Laravel 默认 JSON 响应会自动序列化分页器，但字段名（如 nextPageUrl）、层级（meta 里只有 current_page）、缺失字段（如缺 has_next）都不可控，前端对接容易反复改。
- 不要直接
return response()->json($posts->paginate(10))—— 这等于把框架默认序列化逻辑全交给前端猜 - 正确做法是手动解构：
$paginated = $posts->paginate(10); return response()->json(['items' => $paginated->items(), 'total' => $paginated->total(), 'page' => $paginated->currentPage(), 'page_size' => $paginated->perPage(), 'has_next' => $paginated->hasMorePages()]); - 如果用
simplePaginate()，记得$paginated->items()是空数组时（如请求第 1000 页但数据不足），hasMorePages()仍可能为true，前端必须先判items.length > 0再追加
最常被忽略的点：分页器默认用 request()->url() 构造链接，但如果你的路由是 SPA 模式（如 Nuxt/React Router），或用了自定义查询参数键名（如 pageNum 而非 page），withQueryString() 会失效，这时必须手动拼 path 和 query 参数，不能依赖“自动”。
