Laravel如何自定义分页链接实现模型查询结果分页？

本文共计890个文字，预计阅读时间需要4分钟。

由于 Laravel 默认使用 `app()` 函数来获取服务容器中的实例，以下是对伪原创内容的简化

Laravel 默认使用 `app()` 函数获取服务容器实例。

真正可控的方式是显式指定分页器的 base URL：

• 用 withPath() 强制设置基础路径：$users->withPath('/search')->appends(['q' => request('q')])->links()
• 如果用了命名路由（推荐），优先用 withQueryString() + onEachSide(1) 配合 route() 构造器
• 注意：不要在 withPath() 里写完整 URL（如 https://...），只写路径部分，否则会丢协议和域名

Laravel 10+ 中 LengthAwarePaginator 手动分页时怎么保留 GET 参数

当你不用 Eloquent 的 paginate()，而是自己查总数 + 切片数据（比如调用第三方 API 或原生 SQL），必须手动构造分页器。这时 appends() 不起作用，因为 LengthAwarePaginator 不自动读取请求参数。

正确做法是把当前请求的所有有效查询参数手动传进去：

• 先获取干净参数：$query = request()->except(['page'])
• 构造分页器时传入：new LengthAwarePaginator($items, $total, $perPage, $currentPage, ['path' => request()->url(), 'query' => $query])
• 关键点：path 必须是 request()->url()（不含 query string），不能是 request()->fullUrl()，否则会重复拼接参数
• 如果用了 route() 命名路由，path 改成 route('search', $query) 更安全

render() 输出的 HTML 里 href 属性被转义导致链接失效

这是 Blade 模板中未加 {!! !!} 导致的典型问题。Laravel 分页器的 render() 方法返回的是原始 HTML 字符串，不是已渲染的视图片段。

常见错误写法：{{ $users->links() }} 或 {{ $users->render() }} —— 这会让 <a href="..."> 变成文字显示。

• 必须用 {!! $users->links() !!} 或 {!! $users->render() !!}
• 如果你在组件里封装分页（如 <x-pagination :items="$users" />），组件内也要用 {!! $items->render() !!}
• 别试图用 htmlspecialchars_decode() 补救，那是绕路；根源是模板输出方式不对

API 接口返回分页数据时，为什么 next_page_url 是 null

因为 Laravel 的 API 分页器（Illuminate\Pagination\LengthAwarePaginator）默认不生成 next_page_url 等字段，它只提供 nextPageUrl() 方法，需要你手动映射到响应结构里。

JSON 响应中要带标准分页元信息，得自己组装：

• 不要直接 return response()->json($users)，这样只有数据没有分页链接
• 正确做法：return response()->json(['data' => $users->items(), 'meta' => ['current_page' => $users->currentPage(), 'last_page' => $users->lastPage(), 'next_page_url' => $users->nextPageUrl(), 'prev_page_url' => $users->previousPageUrl()]])
• 注意：nextPageUrl() 返回的是完整 URL，如果服务部署在子路径（如 /api/v1），确保 APP_URL 和 TRUSTED_PROXIES 配置正确，否则生成的 URL 会漏前缀

最易被忽略的一点：分页器的 path 选项在 API 场景下必须显式设为当前接口路径，否则 nextPageUrl() 会基于 Web 路由生成错误链接。