使用php artisan route:cache缓存路由时出现LogicException异常

当执行php artisan route:cache缓存路由时，触发如下LogicException异常：

LogicException : Unable to prepare route [registreren] for serialization. Another route has already been assigned name [auth.register].

相关路由代码 #

主路由文件web.php：

Route::name('auth.')->middleware(['basket'])->group(__DIR__ . '/web/auth.php');
Route::name('client.')->middleware(['basket'])->group(__DIR__ . '/web/client.php');
Route::prefix('admin')->name('admin.')->middleware(['admin'])->group(__DIR__ . '/web/admin.php');

引发异常的auth.php路由片段：

Route::controller(AuthRegisterController::class)->name('register')->middleware('guest')->group(function () {
    Route::get('/registreren', 'view');
    Route::post('/registreren', 'action');
});

排查确认未手动重复定义auth.register，但给分组内路由单独命名后可正常缓存：

Route::controller(AuthRegisterController::class)->name('register.')->middleware('guest')->group(function () {
    Route::get('/registreren', 'view')->name('get');
    Route::post('/registreren', 'action')->name('post');
});

非缓存模式下，route('auth.register')可正常生成URL，仅缓存时触发异常。

原因分析 #

这是Laravel路由缓存的预期行为，异常描述确实存在误导性：

1. 当你在控制器分组上使用->name('register')时，外层分组的auth.前缀会和它拼接，分组内的所有路由（这里是GET、POST两个/registreren路由）都会继承auth.register作为最终名称。
2. 非缓存模式下，Laravel可以通过HTTP请求方法区分同名称、同URL的路由，正常响应请求并生成URL；但路由缓存需要序列化路由信息，要求每个路由名称必须唯一——序列化过程无法区分同名称不同方法的路由，因此抛出「名称已被占用」的异常。

无需大规模重构的解决方案 #

方案1：通过路由别名保留原调用，同时保证缓存唯一性

利用Laravel的路由别名功能，给分组内路由添加唯一名称的同时，保留auth.register的调用兼容性：

Route::controller(AuthRegisterController::class)->name('register.')->middleware('guest')->group(function () {
    // 给GET路由设置别名auth.register，保留原视图调用
    Route::get('/registreren', 'view')->name('index')->alias('auth.register');
    // POST路由使用唯一名称
    Route::post('/registreren', 'action')->name('store');
});

此时路由的实际名称为auth.register.index和auth.register.store，满足缓存唯一性要求，同时route('auth.register')依然可以正常生成GET路由的URL。

方案2：直接给单个路由分配原名称

如果仅需要GET路由对应auth.register，可以调整路由定义，避免分组批量命名：

Route::controller(AuthRegisterController::class)->middleware('guest')->group(function () {
    Route::get('/registreren', 'view')->name('register');
    Route::post('/registreren', 'action')->name('register.store');
});

这样GET路由名称为auth.register，POST为auth.register.store，既满足缓存要求，又不影响原视图调用。

方案3：临时关闭路由缓存（不推荐生产环境使用）

若暂时无法调整路由，可以执行php artisan route:clear清除缓存，依赖动态路由解析运行，但生产环境会损失路由缓存带来的性能提升。

内容的提问来源于stack exchange，提问作者TinusDev