Laravel中间件分组配置教程

本文深入解析了 Laravel 中间件分组（middlewareGroups）的正确配置逻辑与常见陷阱，强调必须在 `app/Http/Kernel.php` 的 `$middlewareGroups` 中显式注册（如 `'admin' => [...]`），而非误塞入全局 `$middleware`；指出基础中间件（如 `StartSession::class`）不可遗漏、执行顺序至关重要（如权限中间件需置于 `SubstituteBindings` 之后），且必须通过 `Route::middleware('admin')->group()` 显式调用才能生效——注册不等于启用；同时澄清带参中间件（如 `throttle:60,1`）严禁放入 `$middlewareGroups`，而应与中间件组并列声明于路由层；最后提醒嵌套分组不会自动继承 prefix/as，需手动拼接命名空间与路径。全文直击开发中极易踩坑的“看似正常却静默失效”场景，提供可立即验证的实操指南：改完即跑 `php artisan route:list`，再用 `curl` 快速确认行为是否符合预期。

middlewareGroups 必须在 app/Http/Kernel.php 里注册，否则路由中写 middleware('admin') 会直接报错「Undefined middleware group」——这不是配置没生效，是压根没被 Laravel 认出来。

中间件组必须先注册到 $middlewareGroups，不能塞进 $middleware

把后台权限中间件（比如 AdminAuthMiddleware::class）加进全局 $middleware 数组，等于给所有请求“无差别安检”：

• / 首页跳登录页
• /storage/app/public/logo.png 返回 401
• /api/health 被拦截，K8s 探针失败

这不是 bug，是设计逻辑错位。正确做法是：只往 $middlewareGroups 里加，例如：

'admin' => [
    \App\Http\Middleware\EncryptCookies::class,
    \Illuminate\Session\Middleware\StartSession::class,
    \App\Http\Middleware\AdminAuthMiddleware::class,
    \App\Http\Middleware\CheckAdminRoleMiddleware::class,
],

注意三点：

• 别漏掉基础中间件（如 StartSession::class），否则 session() 在 admin 路由里不可用
• 顺序很重要：AdminAuthMiddleware 要放在 SubstituteBindings::class 之后，确保路由参数已解析
• 别用 auth 别名——那是 web 组的，admin 组要自己维护完整链

Route::middleware('admin')->group() 才真正触发中间件组

注册完不等于自动生效。你必须在 routes/web.php 或 routes/api.php 中显式调用：

Route::middleware('admin')->prefix('admin')->group(function () {
    Route::get('/dashboard', [AdminController::class, 'index']);
});

常见错误：

• 只写 ->prefix('admin')，不写 ->middleware('admin') → 中间件完全不执行
• 用旧写法 Route::group(['middleware' => 'admin'], ...) → Laravel 5.3+ 已弃用，不报错但无效
• 混用数组和字符串：middleware => auth 缺引号 → PHP 报 Use of undefined constant auth

验证是否生效：运行 php artisan route:list，看对应路由的 Middlewares 列是否显示 admin。

带参中间件（如 throttle:60,1）不能放 $middlewareGroups 里

$middlewareGroups 只接受无参中间件类名字符串。像 throttle:60,1 这种带冒号参数的，不能直接写进去，否则报 Class does not exist。

正确做法是：把它留在路由定义层，和中间件组混用：

Route::middleware(['admin', 'throttle:60,1'])->group(function () {
    Route::get('/logs', [LogController::class, 'index']);
});

要点：

• ['admin', 'throttle:60,1'] 是合法的，Laravel 会分别解析组和单个中间件
• 不要试图在 $middlewareGroups 里写 'throttle:60,1' —— 它不是类名，也不是可实例化的字符串
• 如果需要动态限流（比如按用户角色不同配额），得用闭包中间件或自定义中间件类，再注册到 $routeMiddleware

嵌套分组不会自动继承 prefix 或 as，必须手动拼接

很多人以为外层 prefix => 'admin' + 内层 prefix => 'users' 会自动变成 /admin/users，其实不会。Laravel 的分组是独立作用域：

Route::group(['prefix' => 'admin', 'as' => 'admin.'], function () {
    Route::group(['prefix' => 'users', 'as' => 'users.'], function () {
        Route::get('list', [UserController::class, 'index'])->name('index');
    });
});

结果是：

• URL 是 /users/list（内层 prefix 覆盖外层）
• 路由名是 users.index（不是 admin.users.index）

要实现预期效果，必须显式写全：

Route::group(['prefix' => 'admin', 'as' => 'admin.'], function () {
    Route::group(['prefix' => 'users', 'as' => 'users.'], function () {
        Route::get('list', [UserController::class, 'index'])->name('index');
    });
});

或者更干脆：外层不设 as，内层直接 'as' => 'admin.users.'，然后子路由 ->name('index') 就能生成 admin.users.index。

中间件组看似只是“换个地方写中间件”，但错一个位置、漏一个基础类、少一次显式绑定，就会导致整个后台路由失能——而且问题往往不报错，只表现为 session 不可用、权限校验跳过、静态资源打不开。最稳妥的做法是：改完 Kernel.php 立刻跑 route:list，再 curl 一个 /admin/dashboard 看响应头和状态码，别等上线后查日志。

终于介绍完啦！小伙伴们，这篇关于《Laravel中间件分组配置教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！