如何在 Laravel API 路由中正确启用 Sanctum 认证中间件-php教程-PHP中文网

如何在 Laravel API 路由中正确启用 Sanctum 认证中间件

本文详解如何为 Laravel 的 api.php 路由配置 Sanctum 认证中间件，使 API 路由支持 auth()->user() 调用，并说明与 Web 路由的关键区别及常见实践要点。

本文详解如何为 laravel 的 `api.php` 路由配置 sanctum 认证中间件，使 api 路由支持 `auth()->user()` 调用，并说明与 web 路由的关键区别及常见实践要点。

在 Laravel 中，Sanctum 提供了轻量、安全的 API 认证方案，但其使用方式需严格区分路由类型：Web 路由（web.php）默认启用 session 支持，而 API 路由（api.php）默认无会话、无 CSRF 保护、不共享 session 状态——这意味着即使你为 API 路由添加 auth:sanctum 中间件，也不能直接在 Blade 模板中调用 auth()->user()，除非该请求本身是通过带有效 Sanctum Token 的 API 请求发起的（例如前端通过 Axios 携带 Authorization: Bearer {token} 头访问），且返回的是 JSON 响应，而非渲染 Blade 视图。

⚠️ 重要前提澄清：

API 路由（api.php）本质不用于返回 Blade 视图。若你在 OrderController@index 中尝试 return view('orders.index') 并期望 auth()->user() 在 Blade 中可用，这属于架构误用——Laravel 的 api 中间件组默认禁用 session，Blade 渲染应归属 web 路由；API 路由应专注返回 JSON 数据。

✅ 正确做法分两类：

1. 若目标是「保护 API 接口并获取当前用户信息（JSON 响应）」

在 routes/api.php 中为路由显式添加 auth:sanctum 中间件即可：

use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->prefix('orders')->as('orders.')->controller(OrderController::class)->group(function () {
    Route::get('index', 'index')->name('index'); // 返回 JSON，如：return response()->json(['user' => auth()->user()]);
});

此时 OrderController@index 中可安全调用：

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

public function index()
{
    $user = auth()->user(); // ✅ 返回已认证的 User 实例
    return response()->json([
        'message' => 'Welcome back!',
        'user' => $user->only('id', 'name', 'email')
    ]);
}

? 注意事项：

客户端（如 Vue/React 应用）必须在请求头中携带有效的 Sanctum Token：
Authorization: Bearer {your-sanctum-token}
确保 .env 中已配置 SANCTUM_STATEFUL_DOMAINS=localhost,127.0.0.1（开发环境）或对应域名；
api.php 路由默认使用 api 中间件组（含 throttle:api），无需额外加 web 或 auth.session —— Sanctum 的 token 认证不依赖 session。

2. 若目标是「在 Blade 页面中显示受保护的订单数据」

请将该路由移至 routes/web.php，并复用 Web 认证中间件组合：

// routes/web.php
Route::middleware([
    'auth:sanctum',
    config('jetstream.auth_session'),
    'verified'
])->group(function () {
    Route::get('/orders', [OrderController::class, 'index'])->name('orders.index');
});

控制器中可正常返回视图：

public function index()
{
    $orders = auth()->user()->orders; // ✅ Blade 中亦可直接使用 {{ auth()->user()->name }}
    return view('orders.index', compact('orders'));
}

总结

auth:sanctum 中间件同时适用于 web.php 和 api.php，但语义不同：Web 下配合 session 实现“登录态持久化”，API 下依赖 bearer token 实现“无状态认证”；
不要试图在 api.php 路由中渲染 Blade 视图——这是设计边界问题，违背 RESTful API 原则；
开发时务必检查请求头、跨域配置（CORS）、CSRF 排除（API 路由自动跳过）及 Sanctum Token 的生成与存储逻辑。

遵循以上规范，即可在 Laravel 中安全、清晰地分离认证场景，让 Web 页面与 API 接口各司其职。