分页URL参数丢失时应使用->appends(request()->query())透传全部查询参数；协议适配需配置X-Forwarded-Proto并调用URL::forceScheme('https')；自定义模板需复制到vendor目录并用->links()指定；API分页应直接返回LengthAwarePaginator实例以确保total等元数据完整。
分页结果里 URL 参数丢失了怎么办
默认 paginate() 会保留当前请求的查询参数（比如 ?search=abc&status=active），但一旦你手动拼接分页链接、或用了 appends() 却没传对值，参数就悄无声息地没了。
常见错误现象：?page=2 点进去后变成纯 ?page=2，搜索词、筛选状态全丢；或者 appends() 传了个空数组，反而清掉了原有参数。
- 用
->appends(request()->query())最稳妥，它直接透传全部原始查询参数 - 如果只追加部分参数（比如固定加
locale=zh），写成->appends(array_merge(request()->query(), ['locale' => 'zh'])) - 别在
appends()里传request()->all()—— 它包含 POST 数据、文件、甚至敏感字段，可能引发 414 或安全问题
想改分页链接的域名或协议（比如从 http 切到 https）
Laravel 分页器生成链接时，默认调用 url() 辅助函数，而它依赖当前请求的 Request 实例。如果你部署在反向代理后（如 Nginx + HTTPS 终止），但 PHP 拿不到真实协议头，paginate() 就会输出 http 链接。
使用场景：站点强制 HTTPS、多租户子域名分页、预渲染静态页面时需要绝对路径。
- 确保服务器设置了
$_SERVER['HTTPS'] = 'on'或转发了X-Forwarded-Proto头，并在AppServiceProvider::boot()中调用URL::forceScheme('https') - 不推荐在模板里用
{{ $items->withPath(url('/api/posts')) }}硬编码路径 —— 它绕过路由，且无法自动处理查询参数 - 如果必须动态改 host（如租户
tenant1.example.com→tenant2.example.com），得重写分页器的getUrlRange()方法，或用->withPath()+ 手动拼接完整 URL
自定义分页器的 HTML 结构（不是换 CSS，是换标签和逻辑）
默认 resources/views/vendor/pagination/bootstrap-5.blade.php 是个黑盒模板，但很多人误以为改它就能控制所有行为 —— 实际上，分页器对象本身不负责渲染，只提供数据；模板只是消费方。
性能影响：每次分页都重新编译 Blade 模板无额外开销，但若你在模板里写复杂 PHP 逻辑（比如嵌套查询、多次 count()），会拖慢渲染。
- 复制默认模板到
resources/views/vendor/pagination/custom.blade.php，然后在分页调用处加->links('pagination.custom') - 模板里关键变量是
$elements（数组，每项是字符串或数组），别直接 echo$paginator—— 它不是字符串 - 如果要支持「跳转到指定页」输入框，得自己加
<form>和 POST 路由，Laravel 原生分页器不处理这个逻辑
用 API 返回 JSON 分页数据时，怎么让前端拿到总页数和当前页
paginate() 返回的是 LengthAwarePaginator 实例，转 JSON 时默认只暴露 data、current_page、last_page 等字段，但 total（总数）、per_page、from/to 这些常被前端用于计算页码栏，却容易被忽略。
容易踩的坑：前端靠 last_page 渲染页码条，但当数据为空时 last_page === 0，导致 UI 异常；或没传 per_page，前端无法判断是否该显示“下一页”按钮。
- 统一用
response()->json($items)，它会自动序列化全部分页元信息，包括total、per_page、from、to - 不要手动 new JsonResponse 并只塞
$items->items()—— 那样丢了所有分页上下文 - 如果用了 API 资源类（
JsonResource），记得在 resource 的toArray()里显式加上'meta' => $this->resource->toArray(request())['meta']，否则 meta 会被 Resource 默认过滤掉
分页看着简单，但参数透传、协议适配、模板边界、API 元数据完整性，每个点都卡在「刚好够用」和「线上翻车」之间。尤其多人协作时，有人改了中间件的 request 修改逻辑，分页链接就突然不对了 —— 这种隐性依赖，比代码本身更难 debug。
