如何在 Laravel API 路由中正确使用 Auth 门面-php教程-PHP中文网

如何在 Laravel API 路由中正确使用 Auth 门面

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。

✅ 若需基于 Session 的认证（如调试或混合 Web/API 场景）

可显式启用 session 支持，并定义 api guard（仅限开发/特定场景）：

Laravel Cloud

Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。

下载

在 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 认证。