Laravel Jetstream注册报Auth guard [api]未定义问题咨询

API 探路者

2026-10-1

排查方向

检查config/jetstream.php中的guard配置项
Jetstream存在独立的守卫配置，不会默认继承auth.php的全局默认守卫，需显式指定为web：
```
'guard' => 'web',
```
校验Jetstream安装时选择的栈是否匹配场景
若你使用Web端（Blade/Inertia）场景，安装Jetstream时错误选择了api栈，默认生成的认证逻辑会强制调用api守卫，可重新执行Jetstream安装命令选择对应Web栈，或手动调整后续Fortify配置。
检查config/fortify.php的guard配置
Jetstream底层依赖Fortify处理认证逻辑，Fortify自身的守卫配置优先级高于全局默认配置，需显式设置为web：
```
'guard' => 'web',
```
检查是否开启了不需要的API特性
若你未用到API相关功能，可先注释config/jetstream.php中Features::api()的配置项，该特性开启后会强制依赖api守卫的定义。如果确实需要使用API功能，需要在config/auth.php的guards数组中补充api守卫配置，示例如下：
```
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'api' => [
        'driver' => 'sanctum',
        'provider' => 'users',
        'hash' => false,
    ],
],
```
排查自定义逻辑的guard调用
检查注册后触发的Registered事件的自定义监听器、或者自定义的注册逻辑中，是否存在手动调用auth()->guard('api')的代码。
重载配置后重启服务
确认配置修改后执行php artisan config:clear清除配置缓存，若使用swoole/roadrunner等常驻进程服务，必须重启服务进程才能加载新配置。