Laravel 11.x 中中间件别名必须在 bootstrap/app.php 的 withMiddleware() 方法中通过 $middleware->alias() 显式注册，语法为 $middleware->alias(['key' => Fully\Qualified\Class::class])，注册后方可于路由、控制器等处使用字符串别名，未注册或拼写错误将报错。

在 Laravel 11.x 中，中间件别名必须在 bootstrap/app.php 文件中统一注册，不再使用旧版的 app/Http/Kernel.php 中的 $middlewareAliases 数组。

注册位置：bootstrap/app.php

打开项目根目录下的 bootstrap/app.php，找到 withMiddleware() 方法。所有中间件别名需在此处通过 $middleware->alias() 显式声明：

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

• 语法为：$middleware->alias(['key' => Fully\Qualified\Class::class])
• 例如注册认证和权限中间件：

→ 在 withMiddleware() 内写：

$middleware->alias([
    'auth' => \App\Http\Middleware\Authenticate::class,
    'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
    'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
]);

别名命名注意事项

• 别名只能含字母、数字、下划线和点号（_ 和 .），不能含短横线或空格
• 避免与 Laravel 内置别名冲突（如 auth、web、api）——覆盖后原功能会失效
• 别名区分大小写，建议全小写加点号分隔（如 tenant.check）

注册后如何使用

别名注册完成后，即可在以下任一位置直接使用字符串名称：

• 路由定义中：Route::get('/admin', [AdminController::class, 'index'])->middleware('auth');
• 路由分组中：Route::middleware(['auth', 'role:admin'])->group(...);
• 控制器构造函数中：$this->middleware('permission:edit posts');
• 控制器方法中：public function update() { $this->middleware('permission:edit posts'); }

常见错误提醒

• 未注册就直接在 ->middleware('xxx') 中使用，会报错：Undefined middleware
• 类全名（如 \App\Http\Middleware\CheckRole::class）不能直接传入 ->middleware()，必须先 alias
• 别名拼写错误或大小写不一致，也会触发相同报错
• 若使用 Spatie Permission，确保已正确安装并发布迁移，否则中间件内部校验会失败