写Laravel项目时，中间件传参这件事看似简单，但换成全限定类名写法后，很多细节容易踩坑。比如平时我们习惯了auth:admin这种别名加冒号的写法，一旦在路由里直接写完整的类名App\Http\Middleware\CheckRole::class，参数该往哪里放、用什么符号分隔，就成了一个高频疑问。这篇文章就把这个问题彻底讲透。
中间件传参的基本语法
先回顾一下Laravel中间件接收参数的标准形式。中间件的handle方法除了默认的$request和$next两个参数之外，后面可以追加任意数量的自定义参数。框架在解析中间件时，会把冒号后面按逗号分隔的值依次传入这些自定义形参。
下面是一个典型的带参中间件，用于校验用户角色：
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
class CheckRole
{
public function handle(Request $request, Closure $next, string $role, string $guard = 'web')
{
if (! $request->user() || ! $request->user()->hasRole($role)) {
abort(403, '无权访问该页面');
}
return $next($request);
}
}</code>当中间件注册了别名（比如在app/Http/Kernel.php的$routeMiddleware里注册为role，Laravel 11之后则是在bootstrap/app.php中用withMiddleware注册），路由上可以这样传参：
// 别名写法，role 对应 $role，web 对应 $guard
Route::get('/admin', [AdminController::class, 'index'])
->middleware('role:admin,web');注意参数顺序必须和handle方法的形参顺序严格一致，框架只按位置传递，不会做名称匹配。如果参数个数少于形参个数，缺少的部分会使用默认值；如果传多了，多出来的会被忽略或者直接抛出错误，具体取决于Laravel版本。
全限定类名的传参写法
如果不想注册别名，或者项目里存在同名别名冲突，直接使用全限定类名是完全合法的写法。这时传参的分隔符依然是冒号，多个参数之间依然用逗号分隔，规则与别名写法完全相同。
写法如下：
use App\Http\Middleware\CheckRole;
Route::get('/admin', [AdminController::class, 'index'])
->middleware(CheckRole::class . ':admin,web');
// 或者直接写字符串形式的类名
Route::get('/admin', function () {
return '后台首页';
})->middleware('App\Http\Middleware\CheckRole:admin');这里有个容易出错的点：使用::class常量时，它本身只是类的字符串名称，不带任何参数信息，所以必须用字符串拼接的方式在后面加上冒号和参数，写成CheckRole::class . ':admin'。如果直接写CheckRole::class:admin，那是PHP语法错误，根本编译不过去。
在控制器属性中写全限定类名中间件同样支持传参，示例如下：
namespace App\Http\Controllers;
use App\Http\Middleware\CheckRole;
use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;
class AdminController extends Controller implements HasMiddleware
{
public static function middleware(): array
{
return [
new Middleware(CheckRole::class . ':admin', only: ['index']),
];
}
public function index()
{
return '后台首页';
}
}传统写法则是在基类控制器里定义$middleware数组，Laravel较新版本已推荐使用上面的HasMiddleware接口方式，它更灵活，可以针对具体方法生效。
常见报错与注意事项
第一类常见问题是参数类型不匹配。如果handle方法给自定义参数声明了严格类型（比如int $ttl），而路由上写的是字符串，某些配置下会直接抛出TypeError。稳妥的做法是形参不声明类型，或者在类型前允许null并给默认值。
第二类问题是把分隔符写错。有人习惯写成CheckRole::class(admin)或者用等号，这些都不被支持，Laravel只认冒号加逗号的组合。另外参数值里如果本身包含逗号，需要在中间件内部自行处理，比如把多个值用竖线拼接再在handle里explode拆分。
第三类要注意全局中间件和路由中间件的区别。全局中间件（在Http/Kernel.php的$middleware数组中注册，或Laravel 11的$middleware->append()）不经过路由解析流程，无法通过冒号语法传参，它的自定义参数只会拿到默认值。只有路由中间件和中间件组里的条目才支持传参。
最后提一个排查技巧：如果传参后行为不符合预期，可以用php artisan route:list -v查看路由详情，输出中会列出该路由挂载的所有中间件及其原始参数字符串，能快速确认参数是否真的传进去了。掌握这些规则后，无论是别名还是全限定类名，中间件传参都不再是难题。
Laravel中间件全限定类名参数传递修改时间：2026-09-03 21:26:47