如何在 Laravel API 路由中正确检测用户认证状态-php教程-PHP中文网

如何在 Laravel API 路由中正确检测用户认证状态

Laravel 的 Auth::id() 或 auth('api')->user() 在 API 路由中返回 null，通常并非配置错误，而是因 API 请求默认未携带有效认证凭证（如 Token），导致守卫无法识别已登录用户。本文详解原因、验证方式、正确用法及关键配置要点。

laravel 的 `auth::id()` 或 `auth('api')->user()` 在 api 路由中返回 `null`，通常并非配置错误，而是因 api 请求默认未携带有效认证凭证（如 token），导致守卫无法识别已登录用户。本文详解原因、验证方式、正确用法及关键配置要点。

在 Laravel 中，web 和 api 路由使用完全独立的认证守卫（guard）与中间件栈。routes/api.php 中定义的路由默认由 api 中间件组保护，该组默认启用 throttle:api 并不自动应用 auth:api 认证中间件——这意味着即使你已登录 Web 用户，API 请求也不会继承其会话；反之，API Token 认证也需显式传递且正确配置。

✅ 正确检查认证状态的方式

不要直接调用 Auth::id() 或 auth('api')->user()->id（这会在未认证时触发 Trying to get property 'id' of null 错误），而应先验证认证状态：

use Illuminate\Support\Facades\Auth;

public function create(Request $request)
{
    // ✅ 安全检查：判断当前请求是否通过 api guard 成功认证
    if (Auth::guard('api')->check()) {
        $userId = Auth::id(); // 等价于 Auth::guard('api')->id()
        // ✅ 安全获取用户实例
        $user = Auth::user();
        // 后续业务逻辑...
    } else {
        return response()->json(['error' => 'Unauthenticated'], 401);
    }
}

? 提示：Auth::check() 默认使用 config('auth.defaults.guard')，若你在 config/auth.php 中将 defaults.guard 设为 'api'，则 Auth::check() 即等价于 Auth::guard('api')->check()；但强烈建议显式指定守卫名，避免环境差异引发歧义。

⚙️ 关键配置确认项

确保以下配置已正确设置（缺一不可）：

config/auth.php 中 guards.api 使用 token 驱动（Laravel 9+ 推荐 sanctum 或 passport）：

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

下载
```
'guards' => [
    'api' => [
        'driver' => 'sanctum', // 或 'passport'
        'provider' => 'users',
    ],
],
```

API 路由显式应用认证中间件（routes/api.php）：

use App\Http\Controllers\PayPalController;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:api') // ? 必须添加！
    ->post('/paypal/order/create', [PayPalController::class, 'create']);

前端请求携带有效认证头（如 Sanctum）：

POST /api/paypal/order/create HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

❌ 常见误区与修复

误区：以为 Auth::id() 在 API 中“应该自动工作” → 实际必须满足：① 中间件启用、② 请求带 Token、③ Token 有效且未过期。
误区：混用 web 和 api guard → Auth::guard('web')->user() 永远为 null（无 session 上下文），反之亦然。

调试技巧：临时打印认证信息定位问题：

\Log::info('API Guard user:', [
    'check' => Auth::guard('api')->check(),
    'user' => Auth::guard('api')->user()?->toArray(),
    'token' => $request->bearerToken(),
]);

✅ 总结

Auth::id() 返回 null 是预期行为——它仅反映当前请求的认证结果，而非全局登录状态。解决核心是：显式添加 auth:api 中间件、确保前端发送有效 Token、始终用 Auth::guard('api')->check() 安全判空。切勿绕过认证检查直接访问 user()->id，这是 Laravel API 开发中最易踩坑的实践之一。