Laravel中间件需先用php artisan make:middleware生成于app/Http/Middleware目录，再在Kernel.php中注册到$routeMiddleware等数组，handle方法必须return $next($request)放行，否则请求卡死。
创建和使用 Laravel 中间件其实很直接，关键在于理解它的执行链路和注册位置——写对了逻辑，但放错地方或漏调 $next($request)，中间件就会静默失效。
一、用 Artisan 命令快速生成中间件
在终端运行：
php artisan make:middleware CheckRole
命令会在 app/Http/Middleware/ 下生成一个类文件，结构已预设好 handle() 方法。你只需专注业务逻辑，不用手动写命名空间、use 语句或方法签名。
生成后，Laravel 会自动加上标准注释和类型提示（Laravel 12+ 默认启用 PHP 8.1+ 类型声明），比如：
public function handle(Request $request, Closure $next): Response
二、在 handle() 中写核心逻辑
每个中间件都围绕一个判断做两件事：拦截 or 放行。重点是必须明确返回值：
- 不符合条件时，直接 return 一个响应，比如
return redirect('login')或return response('Forbidden', 403) - 符合条件时，必须调用并返回
$next($request)，否则请求卡死，页面空白且无报错 - 不要用
exit或die终止，这会跳过 Laravel 的响应生命周期，导致 session 不保存、日志不记录、头信息丢失
示例：检查用户是否拥有指定角色
public function handle(Request $request, Closure $next, string $roles): Response
{
$roleList = explode(',', $roles);
if (!Auth::check() || !Auth::user()->hasAnyRole($roleList)) {
return response(['message' => 'Insufficient permissions'], 403);
}
return $next($request);
}
三、正确注册中间件到 Kernel.php
中间件只有注册后才会被框架识别。注册位置决定作用范围：
-
全局中间件：加到
$middleware数组，所有 HTTP 请求都会经过（慎用，比如不要把依赖 session 的中间件放这里，API 路由会报错） -
路由中间件（带参数）：必须加到
$routeMiddleware，例如：'role' => \App\Http\Middleware\CheckRole::class, -
中间件组（如 web / api）：加到
$middlewareGroups对应的数组里，适合批量启用一组功能（如 CSRF、session、加密等）
注意：命名空间不能省略，\App\Http\Middleware\CheckRole::class 缺少 \App\Http\Middleware\ 会导致类找不到。
四、在路由中绑定并传参
注册完成后，在路由定义中使用 ->middleware() 方法绑定：
- 单个中间件：
->middleware('auth') - 多个中间件（按顺序执行）：
->middleware(['auth', 'throttle:60,1']) - 带参数的中间件（冒号分隔）：
->middleware('role:admin,editor')→ 参数admin,editor会自动传入handle()第三个参数
参数解析由你控制，Laravel 不拆解也不校验格式，所以 role:admin|editor 或 role[admin,editor] 都可以，只要你在 handle() 里统一处理即可。
五、调试中间件是否生效的小技巧
如果中间件没反应，别急着重写，先确认三点：
- 在
handle()开头加一行Log::info('CheckRole started');，末尾加Log::info('CheckRole passed');—— 如果只看到第一条日志，说明$next()没调用或提前返回了响应 - 检查浏览器 Network 面板：状态码是 200 但响应体为空，大概率是漏了
return $next($request) - 确认路由匹配的是
web组（有 session）还是api组（无 session），避免在 API 路由里用依赖 session 的中间件
