Laravel 默认未配置 api 认证守卫，直接调用 auth('api') 会报错；解决方法是手动配置 api guard，或改用默认守卫（如 web）并确保 API 请求携带有效会话凭证。
laravel 默认未配置 `api` 认证守卫，直接调用 `auth('api')` 会报错；解决方法是手动配置 `api` guard，或改用默认守卫（如 `web`）并确保 api 请求携带有效会话凭证。
在 Laravel 中，Auth::guard('api') 或 auth('api') 的调用前提是 config/auth.php 中已正确定义名为 api 的 guard。API 路由（routes/api.php）默认不启用 session 认证，且 Laravel 自带的 api guard 实际上在新版本中默认使用 token 驱动（如 Sanctum 或 Passport），而非 session —— 这正是错误 Auth guard [api] is not defined 的根本原因。
✅ 正确配置 api guard（推荐用于无状态 Token 认证）
若你计划使用 API Token（如 Laravel Sanctum），请先确保已安装并发布配置：
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" php artisan migrate
然后在 config/auth.php 的 'guards' 数组中补充：
'api' => [
'driver' => 'sanctum',
'provider' => 'users',
],⚠️ 注意：
driver值必须与已启用的认证驱动一致（如sanctum、passport或token），不可设为'session'—— 因为session驱动依赖 Cookie 和 CSRF，与无状态 API 设计相悖，且api中间件组默认禁用 session。
Laravel Cloud下载Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
✅ 若需基于 Session 的认证（如调试或混合 Web/API 场景）
可显式启用 session 支持，并定义 api guard（仅限开发/特定场景）：
- 在
app/Http/Kernel.php的$middlewareGroups['api']中临时加入：\Illuminate\Session\Middleware\StartSession::class, \Illuminate\View\Middleware\ShareErrorsFromSession::class,
- 在
config/auth.php中添加：'guards' => [ // ... 其他 guard 'api' => [ 'driver' => 'session', 'provider' => 'users', ], ],
此时可在控制器中安全使用：
use Illuminate\Support\Facades\Auth;
public function create(Request $request)
{
if (Auth::guard('api')->check()) {
$user = Auth::guard('api')->user();
return response()->json(['user_id' => $user->id]);
}
return response()->json(['error' => 'Unauthorized'], 401);
}✅ 更简洁稳妥的做法：复用默认 web guard（适用于已登录 Web 会话的 API 调用）
如果你的 API 请求来自已登录的前端（如 Vue SPA 通过同一域名发起请求，且启用了 Cookie），可直接使用默认守卫：
public function create(Request $request)
{
if (Auth::check()) { // 等价于 Auth::guard('web')->check()
$user = Auth::user(); // 等价于 Auth::guard('web')->user()
// ...
}
}✅ 此方式无需修改 auth.php，但要求请求携带有效的 XSRF-TOKEN 和 laravel_session Cookie，且 routes/api.php 应置于 web 中间件组下（不推荐）—— 更佳实践是统一使用 routes/web.php 处理需会话的支付回调，或严格遵循 API 无状态原则，改用 Sanctum Token 认证。
? 总结
- 错误
Auth guard [api] is not defined表明config/auth.php缺少apiguard 配置； - 不要盲目将
apiguard 的 driver 设为session，它违背 RESTful API 设计原则； - 生产环境 API 认证应优先选用 Sanctum 或 Passport，并正确配置
driver => 'sanctum'； - 调试阶段可临时启用 session 支持，但务必在上线前移除；
- 永远通过
Auth::guard('xxx')->check()判断前先确认 guard 存在，避免运行时异常。
