Laravel 12 中使用 stancl/tenancy v4 实现每个租户独立域名，核心是配置多域名识别、租户自动解析及 HTTP 路由隔离：需安装 v4、添加 domain 字段至 Tenant 模型、配置 identification.driver 为 domain、将 InitializeTenancyByDomain 中间件置于 web 组最前、Nginx 泛指同一入口，并在创建租户时显式设置 domain 值。
在 Laravel 12 中使用 stancl/tenancy v4 实现每个租户独立域名，核心是配置多域名识别 + 租户自动解析 + HTTP 请求路由隔离。v4 的设计已移除对子域名的强依赖，支持任意域名（包括根域、二级域、完全不同的域名），但需手动配置 Web 服务器和应用层逻辑。
1. 安装并初始化 tenancy v4
确保项目已升级到 Laravel 12（PHP ≥ 8.2），然后安装：
composer require stancl/tenancy:^4.0
发布配置与迁移：
php artisan tenancy:install<br>php artisan migrate
运行后会生成 config/tenancy.php 和租户相关数据表（如 tenants）。注意：v4 默认不创建租户中间件或自动域名绑定，需自行集成。
2. 配置租户域名字段与模型
v4 不强制要求域名字段，但推荐在 Tenant 模型中添加 domain 字段用于存储租户专属域名：
php artisan make:migration add_domain_to_tenants_table --table=tenants
在迁移中添加：
$table->string('domain')->unique()->nullable();更新 app/Models/Tenant.php，确保可批量赋值：
protected $fillable = ['id', 'domain', /* 其他字段 */];
3. 启用域名识别驱动并注册中间件
编辑 config/tenancy.php，将识别方式设为 domain：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
'identification' => [<br> 'driver' => 'domain',<br> 'cache_ttl' => 3600,<br>],
在 app/Http/Kernel.php 的 $middlewareGroups['web'] 中，**确保 \Stancl\Tenancy\Middleware\InitializeTenancyByDomain::class 在路由中间件之前执行**（例如放在 EncryptCookies 后、VerifyCsrfToken 前）：
\Stancl\Tenancy\Middleware\InitializeTenancyByDomain::class,
该中间件会根据当前请求的 Host 头，在 tenants 表中查找匹配的 domain 记录，并初始化对应租户上下文（数据库连接、缓存前缀等）。
4. Web 服务器配置（Nginx / Apache）
关键：所有租户域名必须指向同一 Laravel 应用入口（public/index.php），不能做反向代理分发或单独虚拟主机隔离。
Nginx 示例（泛解析或多个 server 块均可）：
server {<br> listen 80;<br> server_name *.example.com example.com tenant-a.com tenant-b.net;<br> root /var/www/laravel12/public;<br> index index.php;<br><br> location / {<br> try_files $uri $uri/ /index.php?$query_string;<br> }<br><br> location ~ \.php$ {<br> fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;<br> fastcgi_index index.php;<br> fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;<br> include fastcgi_params;<br> }<br>}✅ 这样 tenant-a.com 和 shop.b-company.net 都能被 Laravel 接收到，再由 InitializeTenancyByDomain 中间件识别并加载对应租户。
5. 创建租户时设置 domain
创建租户时，显式指定域名：
$tenant = Tenant::create([<br> 'id' => Str::uuid(),<br> 'domain' => 'tenant-a.com',<br>]);<br><br>// 初始化租户数据库等资源<br>$tenant->run(function () {<br> Artisan::call('migrate', ['--force' => true]);<br>});之后访问 http://tenant-a.com 即可自动进入该租户上下文。Laravel 路由、Eloquent 查询、队列任务等均默认作用于该租户环境。
6. 注意事项与常见问题
- HTTPS 证书需覆盖所有租户域名（推荐用 Wildcard 或多域名 SAN 证书）
- 本地开发可用
/etc/hosts绑定多个域名到127.0.0.1测试 - 若使用 Laravel Octane，需启用
--watch并确保租户配置热重载（v4 支持，但需确认tenancy.php中cache_ttl合理） - 避免在
config/文件中硬编码租户相关路径或 URL，一律通过Tenant::current()动态获取 - 邮件、通知中的链接需使用租户域名：用
URL::to('/')或route('home', [], false)配合tenancy.url_generator驱动
