middlewaregroups 必须在 app/http/kernel.php 的 $middlewaregroups 中注册，否则路由中 middleware('admin') 会报「undefined middleware group」；需包含基础中间件如 startsession::class，adminauthmiddleware 要置于 substitutebindings 之后，且必须显式调用 route::middleware('admin')->group() 才生效。
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。
Kernel.php 立刻跑 route:list，再 curl 一个 /admin/dashboard 看响应头和状态码，别等上线后查日志。
