Laravel多域名路由配置详解

本文深入解析 Laravel 中实现多域名路由的核心机制 Route::domain()，强调其是唯一真正基于 HTTP Host 请求头进行匹配的官方方案，并系统梳理了实际开发中极易踩坑的关键细节：必须使用纯域名（不含协议或路径）、本地需配置 /etc/hosts、通配符子域名参数须显式接收并配合 where() 限制、URL 生成与重定向需手动干预以适配当前域名、路由定义顺序必须确保 domain 组前置且及时清缓存；更指出多域名落地的真正挑战不在路由声明本身，而在于 Session 共享、链接生成、API 响应、日志记录等全链路对 Host 的依赖协同——任一环节疏漏都将导致功能“半残”，堪称一份直击痛点、兼顾原理与实战的硬核指南。

Route::domain() 是唯一能真正按 Host 头匹配多域名的机制，其他方式（比如 prefix 或 middleware 套壳）都不生效。

Route::domain() 必须写纯域名，不能带协议或路径

常见错误是把 https://admin.example.com 或 admin.example.com/dashboard 直接塞进 Route::domain()，结果路由永远不匹配。Laravel 只比对 HTTP 请求头里的 Host 字段，且只接受形如 admin.example.com 或 {sub}.example.com 的纯域名字符串。

• ✅ 正确：Route::domain('admin.example.com')、Route::domain('{sub}.example.com')
• ❌ 错误：Route::domain('https://admin.example.com')、Route::domain('admin.example.com/api')
• 本地开发需同步改 /etc/hosts：加一行 127.0.0.1 admin.example.com，否则浏览器发不出带该 Host 的请求

通配符子域名必须显式接收参数，否则拿不到值

写 Route::domain('{sub}.example.com') 只是声明了变量名，不等于自动注入。闭包或控制器方法签名里必须显式列出该参数，否则 request()->route('sub') 会返回 null，甚至抛出 MissingParameterException。

• 闭包中要这样写：function ($sub) { return "Sub: $sub"; }
• 控制器方法也要对应加参：public function index($sub) { ... }
• 配合 where() 限制合法值更安全：->where('sub', 'shop|admin|api')，防住 hacker.example.com 这类意外匹配

URL 生成和重定向默认不随域名切换，必须干预

url()、route()、redirect()->route() 全部依赖 APP_URL 或 config('app.url')。多域名下若不处理，所有链接都会指向 APP_URL 配置的那个域名，哪怕当前请求来自 api.example.com。

• 最简方案：在 AppServiceProvider@register() 里加 \URL::forceRootUrl(\Request::getSchemeAndHttpHost());
• 如果用了反向代理（如 Nginx），确保 TrustProxies 中配置了可信 IP，否则 getSchemeAndHttpHost() 可能读错 Host
• 重定向不能靠 redirect()->route('admin.dashboard') 自动换域，得显式写完整地址：redirect('https://admin.example.com/dashboard') 或用 url() 拼

路由顺序决定 fallback 行为，domain 组必须前置

Laravel 路由匹配是顺序执行的。如果把无约束的 Route::get('/', ...) 写在 Route::domain('admin.example.com') 前面，那么所有根路径请求都会被前者捕获，admin.example.com/ 就永远进不去 domain 组。

• 正确顺序：先定义所有 Route::domain() 组，最后放通用 fallback 路由
• 多个 domain 组之间无优先级，但必须都早于无 domain 约束的路由
• 生产环境记得跑 php artisan route:clear，否则缓存可能让新 domain 规则不生效

真正麻烦的从来不是写几行 Route::domain()，而是后续所有依赖 Host 的环节——Session 共享要设 SESSION_DOMAIN=.example.com，邮件模板里的链接要用 url()，API 返回的跳转地址得动态拼，连日志里记录的 referer 都可能因代理头错乱。这些点不串起来，多域名就是半残状态。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Laravel多域名路由配置详解》文章吧，也可关注golang学习网公众号了解相关技术文章。