Laravel 8使用Spatie laravel-multitenancy时无当前租户的报错处理

故障现象 #

• 运行环境：Laravel v8 版本，集成 Spatie laravel-multitenancy 多租户扩展
• 触发报错的访问地址：http://one.localhost:8000/，该域名对应的租户未在系统租户表中定义
• 抛出的错误详情：Spatie\Multitenancy\Exceptions\NoCurrentTenant，错误触发逻辑为「当前路由需要绑定有效租户上下文，但未匹配到可激活的租户实例」
• 现有路由配置 web.php 内容：

Route::domain('{tenant}.localhost')->middleware('tenant')->group(function(){
    Route::get('/', function ($tenant) {
        return $tenant;
        // return view('welcome');
    });
});

Route::domain('localhost')->group(function(){
    Route::get('/', function () {
        return view('welcome');
    });
});

Route::middleware(['auth:sanctum', 'verified'])->get('/dashboard', function () {
    return view('dashboard');
})->name('dashboard');

报错核心原因 #

• 你给所有 {tenant}.localhost 前缀的子域名路由组绑定了 tenant 中间件，该中间件的固定逻辑是：根据请求携带的子域名参数，匹配租户数据表中对应的有效记录，匹配成功才会激活租户上下文、放行请求
• 访问 one.localhost:8000 时，提取到的子域名参数为 one，但租户表中没有对应 slug 为 one 的有效租户记录，中间件完成全量匹配流程后仍未找到可激活的租户实例，就会直接抛出 NoCurrentTenant 异常
• 当前项目未针对该异常配置兜底捕获逻辑，导致原始错误直接暴露给访问端

落地处理方案 #

1. 给租户中间件补全异常兜底逻辑 #

定位到项目中处理租户激活的中间件（扩展默认类为 Spatie\Multitenancy\Http\Middleware\NeedsTenant，也可能是你自定义的租户绑定中间件），修改异常捕获规则：

• 当捕获到 NoCurrentTenant 异常时，不再直接抛出错误，而是重定向到主域名下的404页面，或者跳转到租户不存在的提示页
• 参考改写示例：

public function handle($request, Closure $next)
{
    try {
        // 保留原有租户匹配、激活逻辑
        $tenant = $this->resolveTenantFromRequest($request);
        app(Tenant::class)->setCurrent($tenant);
    } catch (NoCurrentTenant $exception) {
        // 无匹配租户时，直接跳转主域404页
        return redirect()->to('/404', 302, [], 'http://localhost:8000');
    }

    return $next($request);
}

2. 匹配测试场景的租户记录 #

• 如果是本地联调需要访问 one.localhost 域名，直接在租户数据表中新增一条子域名标识为 one 的有效记录，确保子域名提取的参数和租户表中存储的 slug/域名字段值完全一致
• 本地环境需同步在系统 hosts 文件中把 one.localhost 指向 127.0.0.1，避免域名解析异常

3. 优化路由分层绑定规则 #

• 将不需要租户上下文的公共路由（主域首页、404页、登录授权页）从带子域名匹配的路由组中拆出，不要被 tenant 中间件拦截
• 仅对实际需要租户数据隔离的业务路由，单独绑定 tenant 中间件，避免无差别拦截所有子域名请求

内容的提问来源于stack exchange，提问作者Harish J Gowda