Laravel 11中间件注册统一收口至bootstrap/app.php:全局中间件通过$middleware->use()、->web()、->api()显式声明;路由中间件须先$middleware->alias()注册别名,再在路由或控制器中调用,不再支持$routeMiddleware自动映射。

核心区别在于注册入口统一收口、声明方式显式化、自动映射被移除。Laravel 11 彻底重构中间件注册机制,不再依赖 app/Http/Kernel.php 和 $routeMiddleware 数组,所有配置必须集中在 bootstrap/app.php 中完成。
全局中间件:从 Kernel.php 迁移到 app.php
Laravel 10 全局中间件在 app/Http/Kernel.php 的 $middleware、$middlewareGroups 数组中声明;Laravel 11 删除了该文件,改用 bootstrap/app.php 中的 withMiddleware() 闭包:
-
$middleware->use([...])替代旧版$middleware数组,用于每次请求都执行的中间件(如日志、CSP头) -
$middleware->web([...])和$middleware->api([...])显式定义 web/api 中间件链,不可为空数组但可传空切片 - 原
$middlewareGroups已由框架固化,无法自定义或覆盖
路由中间件:必须先 alias 再调用
Laravel 10 支持在 Kernel.php 的 $routeMiddleware 中注册别名后,直接在路由中写 ->middleware('auth');Laravel 11 禁用该机制:
- 必须在
withMiddleware()中用$middleware->alias('auth', \App\Http\Middleware\Authenticate::class)显式绑定别名 - 未 alias 的中间件类全名不能直接用于
->middleware(),否则报 “Undefined middleware” - 控制器中使用
middleware('auth')或构造函数注入,也必须基于已 alias 的字符串
中间件组语义变更:“web” 和 “api” 不再是魔法字符串
过去 ->middleware('web') 是靠 Kernel 配置驱动的快捷方式;Laravel 11 中它只是执行链入口:
-
->middleware('web')实际等价于展开$middleware->web([...])中注册的所有中间件 - 带参数的中间件(如
throttle:60,1)不能塞进web()或api()调用,只能单独加在路由上 - 多个中间件组合时顺序敏感,例如
['auth:sanctum', 'throttle:api']必须把认证放前面,否则后续中间件可能拿不到用户上下文
常见错误示例(Laravel 11 中会失败)
- 还在
config/app.php手动注册RouteServiceProvider→ 启动报 “Provider already registered” - 沿用
Route::group(['middleware' => 'web'], ...)却没提前 alias → 中间件不执行,且php artisan route:list查不到生效痕迹 - 试图在
$middleware->web()里传入throttle:api→ 报错或静默忽略


















