Stancl/Tenancy v4 原生支持 Laravel 11，租户识别须在请求早期通过子域名完成，需配置自定义 SubdomainIdentifier 类并注册到 config/tenancy.php，确保 TenancyServiceProvider 优先加载。
Stancl/Tenancy 默认通过子域名识别租户，Laravel 11 中集成需确保请求进入前就完成租户解析，避免中间件或路由层才处理——否则模型、数据库连接、配置加载都可能出错。Claude Code 可辅助生成健壮、符合 Tenancy v4+ 规范的识别逻辑，但需你明确项目结构和域名策略。
确认 Tenancy 版本与 Laravel 11 兼容性
Stancl/Tenancy v4（当前稳定版）已原生支持 Laravel 11。使用前请检查：
– composer require stancl/tenancy:^4.0
– 运行 php artisan tenancy:install 生成配置与迁移
– 确保 config/tenancy.php 中 'identification' => 'subdomain' 已启用
自定义子域名识别器（推荐用 Claude Code 辅助编写）
Tenancy 允许你替换默认识别器。Claude Code 可帮你生成一个更灵活的 SubdomainIdentifier 类，比如支持多级子域（如 shop.example.com 或 api.us-west.myapp.com），或排除特定子域（如 admin.example.com 不走租户逻辑）。
你可以向 Claude Code 提供如下提示：
- “生成一个 Laravel 11 兼容的 Stancl/Tenancy v4 自定义 SubdomainIdentifier 类，从 Host 头提取主子域（忽略 www、admin、api 等保留子域），支持 .dev/.test/.localhost 本地开发域名”
- “输出完整 PHP 类，含命名空间、implements IdentifierInterface、use TenantSetters、handle() 方法，返回 Tenant 模型实例或 null”
- “添加注释说明如何注册到 config/tenancy.php 的 'identifier' 配置项”
注册识别器并验证请求生命周期位置
Tenancy 的租户识别必须在 Laravel 内核早期触发（早于服务提供者注册、配置加载）。Claude Code 可帮你确认关键点：
- 将自定义识别器类放入
app/Tenancy/Identifiers/SubdomainIdentifier.php - 在
config/tenancy.php中设置：'identifier' => App\Tenancy\Identifiers\SubdomainIdentifier::class, - 确保
App\Providers\TenancyServiceProvider已在config/app.php的providers数组中，并排在App\Providers\AppServiceProvider之前 - 运行
php artisan tenancy:migrate和php artisan tenancy:seed初始化租户数据
调试与验证技巧（Claude Code 可生成测试用例）
子域名识别失败常表现为 404、数据库连接错乱或 tenant_id 为 null。Claude Code 可快速生成诊断代码：
- 写一个 Artisan 命令，接收 --host 参数，模拟请求并打印识别结果：
php artisan tenancy:test-identifier --host=client1.example.com - 在
App\Tenancy\Identifiers\SubdomainIdentifier@handle()开头加Log::debug('Host header:', ['host' => $request->getHost()]); - 用 PHPUnit 写单元测试，传入不同 Host 头，断言是否返回正确 Tenant 实例或 null
不复杂但容易忽略：Laravel 11 的 HTTP 内核启动更早，务必确保识别器不依赖尚未初始化的 Facade 或 Config；所有租户相关逻辑（如数据库切换、缓存前缀）均由 Tenancy 自动接管，无需手动调用 Tenant::set()。
