本文详解如何为 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 中可安全调用：
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 接口各司其职。
