自定义中间件组必须注册到 $middlewareGroups 而非 $middleware，因为 $middleware 是全局应用的，会导致 /storage、/health 等非业务路由被无差别拦截；而 $middlewareGroups 可按需绑定到特定路由组，确保精准控制执行范围。
自定义中间件组必须注册到 $middlewareGroups，不能塞进 $middleware；否则所有请求（包括 /storage 图片、/health 接口）都会被拦截。
为什么不能往 $middleware 里加后台中间件
全局中间件数组 $middleware 在 app/Http/Kernel.php 里，它对每个 HTTP 请求无差别执行。哪怕你只想要 /admin 路由走权限校验，一旦把 AdminAuthMiddleware::class 塞进这里：
- 网站首页
/会跳登录页 -
/storage/app/public/logo.png返回 401 -
/api/health被拒绝，K8s 探针失败
这不是“没配好”，是设计意图完全错位。
正确注册方式：加到 $middlewareGroups['admin']
打开 app/Http/Kernel.php，在 $middlewareGroups 数组里新增一个键值对：
protected $middlewareGroups = [
'web' => [ /* ... */ ],
'api' => [ /* ... */ ],
'admin' => [
\App\Http\Middleware\EncryptCookies::class,
\Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
\Illuminate\Session\Middleware\StartSession::class,
\Illuminate\View\Middleware\ShareErrorsFromSession::class,
\App\Http\Middleware\VerifyCsrfToken::class,
\Illuminate\Routing\Middleware\SubstituteBindings::class,
\App\Http\Middleware\AdminAuthMiddleware::class,
\App\Http\Middleware\CheckAdminRoleMiddleware::class,
],
];注意几点：
- 别漏掉基础中间件（如
StartSession），否则session()在 admin 路由里不可用 - 顺序很重要：
AdminAuthMiddleware应该在SubstituteBindings之后，确保路由参数已解析 - 别用
auth别名——那是web组的，admin组要自己维护完整链
路由分组时必须显式调用 middleware('admin')
注册完不等于自动生效。你在 routes/web.php 中必须这样写：
Route::middleware('admin')->prefix('admin')->group(function () {
Route::get('/dashboard', [AdminController::class, 'index']);
Route::get('/users', [AdminController::class, 'list']);
});常见错误：
- 只写
->prefix('admin')，不写->middleware('admin')→ 中间件完全不触发 - 写成
middleware(['admin'])（带数组）→ Laravel 5.8+ 不报错但无效，应直接传字符串'admin' - 在闭包里再调一次
middleware()→ 多余，且可能覆盖外层配置
如果中间件需要参数（比如 role:super），别试图在分组里写 'admin.role:super' —— 分组只认已注册的组名，参数只能单条路由加：->middleware('role:super')。
调试时优先跑 php artisan route:list
改完中间件组和路由后，运行这个命令能立刻验证是否生效：
$ php artisan route:list | grep admin
你会看到每条 admin 路由的 Middleware 列明确写着 admin，而不是一堆零散类名。如果列里还是空的或只有 web，说明：
- 路由文件没重载（清缓存：
php artisan route:clear） -
middleware('admin')拼写错误（大小写敏感） -
$middlewareGroups['admin']键名少了个引号或写成了admin:
真正容易被忽略的是：中间件组里的类路径必须可 autoload，且构造函数不能有未提供默认值的依赖——Laravel 在路由解析阶段就尝试实例化它们，此时容器尚未完全启动。
