Laravel 9：使用自定义Guard时API路由用户认证失效问题

以下是针对你遇到的问题的排查步骤和解决方案：

1. 明确API路由的认证中间件使用自定义Guard #

默认的auth中间件会调用配置文件中设定的默认Guard（通常为web），因此必须在API路由中明确指定使用vcs Guard：

// routes/api.php
Route::get('/rooms', [RoomController::class, 'index'])->middleware('auth:vcs');

2. 为API中间件组添加Session相关依赖 #

Laravel的api中间件组默认不启用Session（适配Token认证场景），但你的认证流程依赖Session，需要修改app/Http/Kernel.php，将Session相关中间件加入api组：

protected $middlewareGroups = [
    'api' => [
        \App\Http\Middleware\EncryptCookies::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \Illuminate\Session\Middleware\StartSession::class, // 新增Session启动中间件
        \Illuminate\Routing\Middleware\SubstituteBindings::class,
    ],
];

如果不想全局启用Session，也可为单个API路由单独绑定这些中间件：

Route::get('/rooms', [RoomController::class, 'index'])
    ->middleware([
        'auth:vcs',
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
        \App\Http\Middleware\EncryptCookies::class
    ]);

3. 验证自定义Guard与Provider的配置正确性 #

确保config/auth.php中正确配置了vcs Guard和对应的clients Provider：

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'vcs' => [
        'driver' => 'session', // 匹配你的Session认证方式
        'provider' => 'clients',
    ],
],

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
    'clients' => [
        'driver' => 'eloquent',
        'model' => App\Models\Client::class, // 关联你的Client模型
    ],
],

4. 确认手动登录时调用正确的Guard #

登录流程中必须明确使用vcs Guard的login方法，而非默认Guard：

// 动态创建临时用户后的登录逻辑
$client = Client::create([/* 临时用户数据 */]);
Auth::guard('vcs')->login($client); // 确保用vcs Guard完成登录

5. 处理CSRF验证问题（若启用Session） #

如果API路由依赖Session认证，Laravel会校验CSRF令牌，可通过以下方式处理：

• 在App\Http\Middleware\VerifyCsrfToken中排除API路由：

protected $except = [
    '/api/*',
];

• 测试时（如Insomnia），携带XSRF-TOKEN请求头，值从Cookie中的XSRF-TOKEN字段获取。

6. 检查Session Cookie的域名与路径配置 #

确保config/session.php中的Cookie配置能覆盖API路由：

'domain' => env('SESSION_DOMAIN', null), // 设为主域名，确保API子域名可共享Cookie
'path' => '/', // 允许所有路径访问Session Cookie

7. 调试Guard的用户检索逻辑 #

可在自定义Guard的user方法中添加日志，排查Session中是否存储了正确的用户ID，以及Provider能否正常检索用户：

// 示例：基于Session的Guard的user方法
public function user()
{
    if (!is_null($this->user)) {
        return $this->user;
    }

    $clientId = $this->session->get($this->getName());
    Log::info('VCS Guard Session Client ID: ' . $clientId); // 日志记录Session中的用户ID

    if (!is_null($clientId) && $this->user = $this->provider->retrieveById($clientId)) {
        $this->fireAuthenticatedEvent($this->user);
    }

    return $this->user;
}

内容的提问来源于stack exchange，提问作者NKnuelle