Laravel 8.x 创建自定义路由中间件需三步：生成文件（php artisan make:middleware CheckRole）、编写handle逻辑（接收$request、$next及冒号传参，必须return响应或$next($request)）、注册别名到Kernel.php并路由绑定（如middleware('role:admin')）。
在 Laravel 8.x 中创建自定义路由中间件，核心是三步：生成文件、编写逻辑、注册并绑定到路由。重点在于中间件位置必须正确、handle 方法必须返回响应或 $next($request)，且参数传递要用冒号语法。
生成中间件文件
用 Artisan 命令一键创建，自动放对位置、设好命名空间：
- 运行
php artisan make:middleware CheckRole - 文件会生成在
app/Http/Middleware/CheckRole.php - 命名空间自动为
namespace App\Http\Middleware;，别手动建错目录（比如丢进app/Middleware或app/Http/根目录）
编写 handle 方法逻辑
这是中间件的核心。注意接收参数方式和终止请求的写法：
- 必须接收
Request $request和Closure $next两个参数 - 如需从路由传参（比如权限标识），加第三个参数：
string $role，Laravel 会自动注入冒号后的值 - 判断不通过时，必须显式
return response()->json(..., 403)或return redirect(...)；只 throw 异常不 return 响应，前端可能收不到正确状态码 - 放行时务必
return $next($request)，漏掉会导致整个请求链中断
注册并应用到路由
中间件要被识别，得先在 app/Http/Kernel.php 的 $routeMiddleware 数组中声明别名：
- 在
$routeMiddleware里添加：'role' => \App\Http\Middleware\CheckRole::class - 别名建议小写+点号分隔（如
can.edit），避免特殊字符 - 然后在
routes/web.php或routes/api.php中使用：Route::get('/admin', [AdminController::class, 'index'])->middleware('role:admin'); - 多个参数用逗号分隔：
->middleware('role:admin,editor')，handle 方法对应加$role, $extra参数
常见避坑点
这些细节出错会导致中间件不生效或报错：
- 手写文件时，命名空间写成
App\Middleware或App\Http\middleware（小写 m）——Laravel 找不到类 - 在 handle 里做 DB 查询但没缓存，高频接口下拖慢响应
- 误以为能在路由链上直接调用中间件方法，比如
->hasPermissionTo('view')—— 路由对象根本不认识中间件实例 - 全局注册了本该路由级使用的权限中间件，导致 API 接口意外启动 session 或触发登录检查
