在 Laravel 11 中为 API 路由加中间件需先在 Kernel.php 中正确定义单个中间件（$routeMiddleware）或中间件组（$middlewareGroups），再于 routes/api.php 中通过 Route::middleware() 链式调用，严禁混用、嵌套或引入 web 中间件。
在 Laravel 11 中给 API 路由组加中间件，核心是「先注册、再引用、分清职责」。不能直接写 middleware('xxx') 就生效，必须确保中间件或中间件组已在内核中正确定义，且用法符合路由上下文（尤其是区分 api.php 和 web.php）。
确认中间件类型：是单个中间件，还是中间件组？
两者注册和调用方式不同：
-
单个中间件（如
auth:api、throttle:60,1）需注册到$routeMiddleware数组，然后在路由中直接使用字符串名（带参数也支持） -
中间件组（如
api、admin）必须注册到$middlewareGroups，才能在->middleware('组名')中调用
例如，auth:api 是单个中间件（来自 $routeMiddleware['auth']），而 api 是中间件组（来自 $middlewareGroups['api']）。混用会导致认证失败或限流失效。
在 routes/api.php 中正确绑定中间件
推荐使用链式调用，清晰、安全、可读性强：
- 对整个 API 组统一加中间件组（如限流+绑定）：
Route::middleware('api')->group(function () {<br> Route::get('/users', [UserController::class, 'index']);<br> }); - 对需要登录的子集叠加认证中间件：
Route::middleware(['api', 'auth:api'])->group(function () {<br> Route::get('/profile', [ProfileController::class, 'show']);<br> }); - 避免嵌套多个
middleware()调用；多个中间件应合并进一个数组，顺序敏感（如auth:api必须在throttle后执行才合理）
检查并配置 app/Http/Kernel.php
这是最容易出错的环节。Laravel 11 默认已定义 'api' 组，但自定义组（如 'v1' 或 'signed'）必须手动注册：
- 打开
app/Http/Kernel.php，找到$middlewareGroups - 在
'api'下添加你的组（键名即路由中使用的名称）：
'v1' => [<br> \App\Http\Middleware\EnsureApiVersion::class,<br> \Illuminate\Routing\Middleware\SubstituteBindings::class,<br> ],
- 确保路径类名完整、拼写正确，且不遗漏基础中间件（如
SubstituteBindings对模型绑定必需）
注册后，就能在 routes/api.php 中直接写 ->middleware('v1')。
特别注意：API 路由不要加 web 中间件
routes/api.php 默认不加载 web 中间件组（无 session、CSRF、cookie 加密等）。强行加上会引发异常或静默失效：
- 别写
->middleware(['web', 'auth:api'])—— session 在 API 场景中通常不需要，且可能破坏无状态设计 - 如果确实要共享部分逻辑（如日志），应单独提取为无状态中间件，注册到
$routeMiddleware，再按需引入 - 登录/注册等免认证接口，只用
api组（保障限流和绑定），不加auth:api
