Laravel12怎么用stancl/tenancyv4给每个租户配置独立域名-php教程-PHP中文网

Laravel 12 中使用 stancl/tenancy v4 实现每个租户独立域名，核心是配置多域名识别、租户自动解析及 HTTP 路由隔离：需安装 v4、添加 domain 字段至 Tenant 模型、配置 identification.driver 为 domain、将 InitializeTenancyByDomain 中间件置于 web 组最前、Nginx 泛指同一入口，并在创建租户时显式设置 domain 值。

laravel12怎么用stancl/tenancyv4给每个租户配置独立域名

在 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

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 驱动