Laravel8升级至11后访问Sanctum/Fortify API出现throttle类不存在错误

问题 #

将Laravel 8按官方文档升级至11后，访问Sanctum和Fortify相关API时出现限流相关错误，错误日志如下：

[2024-12-11 10:47:30] local.ERROR: Target class [throttle] does not exist. {"exception":"[object] (Illuminate\Contracts\Container\BindingResolutionException(code: 0): Target class [throttle] does not exist. at /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php:879)
[stacktrace]
#0 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(758): Illuminate\Container\Container->build()
#1 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(851): Illuminate\Container\Container->resolve()
#2 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(694): Illuminate\Foundation\Application->resolve()
#3 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(836): Illuminate\Container\Container->make()
#4 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(206): Illuminate\Foundation\Application->make()
#5 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(180): Illuminate\Foundation\Http\Kernel->terminateMiddleware()
#6 /home/yannick/dev/NetDesk/backend/public/index.php(55): Illuminate\Foundation\Http\Kernel->terminate()
#7 /home/yannick/dev/NetDesk/backend/server.php(21): require_once('...')
#8 {main}

[previous exception] [object] (ReflectionException(code: -1): Class "throttle" does not exist at /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(877))
[stacktrace]
#0 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(877): ReflectionClass->__construct()
#1 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(758): Illuminate\Container\Container->build()
#2 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(851): Illuminate\Container\Container->resolve()
#3 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Container/Container.php(694): Illuminate\Foundation\Application->resolve()
#4 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(836): Illuminate\Container\Container->make()
#5 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(206): Illuminate\Foundation\Application->make()
#6 /home/yannick/dev/NetDesk/backend/vendor/laravel/framework/src/Illuminate/Foundation/Http/Kernel.php(180): Illuminate\Foundation\Http\Kernel->terminateMiddleware()
#7 /home/yannick/dev/NetDesk/backend/public/index.php(55): Illuminate\Foundation\Http\Kernel->terminate()
#8 /home/yannick/dev/NetDesk/backend/server.php(21): require_once('...')
#9 {main}
"}

已在backend/app/Http/Kernel.php中配置路由中间件别名：

//backend/app/Http/Kernel.php
protected $routeMiddlewareAliases = [
        'auth' => \App\Http\Middleware\Authenticate::class,
        'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
        'type.customer' => CustomerMiddleware::class,
        'type.tech' => TechnicianMiddleware::class,
        'cache.headers' => \Illuminate\Http\Middleware\SetCacheHeaders::class,
        'can' => \Illuminate\Auth\Middleware\Authorize::class,
        'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
        'password.confirm' => \Illuminate\Auth\Middleware\RequirePassword::class,
        'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
        'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
        'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
        'role' => \Spatie\Permission\Middlewares\RoleMiddleware::class,
        'permission' => \Spatie\Permission\Middlewares\PermissionMiddleware::class,
        'role_or_permission' => \Spatie\Permission\Middlewares\RoleOrPermissionMiddleware::class,
    ];

部分API路由示例：

Route::get('getTicketCategories', [DataController::class, 'getTicketCategories']);
Route::get('getPlanificationTypes', [DataController::class, 'getPlanificationTypes']); 
Route::get('getDashboardPoints', [DataController::class, 'getDashboardPoints']);

虽已配置相关内容，但问题仍未解决，求排查思路及解决办法。

排查与解决步骤 #

• 确认Kernel类结构：Laravel 11要求路由中间件别名定义在$routeMiddlewareAliases属性中，同时确保你的App\Http\Kernel类正确继承自Illuminate\Foundation\Http\Kernel，避免基类错误导致别名无法被框架识别。
• 清理框架缓存：升级后旧缓存可能残留，执行以下命令清空所有缓存：

  php artisan cache:clear
  php artisan route:clear
  php artisan config:clear
  php artisan optimize:clear
  

• 检查依赖完整性：运行composer install重新安装依赖，确保Illuminate\Routing\Middleware\ThrottleRequests类存在于vendor/laravel/framework目录中，避免升级过程中依赖缺失导致类找不到。
• 排查第三方包路由配置：Sanctum和Fortify的默认路由可能自动使用throttle中间件，检查这两个包的配置文件（如config/fortify.php），确认限流配置是否正确引用了中间件别名，或是否存在硬编码的类路径错误。
• 检查全局/路由组中间件：查看全局中间件数组、API路由组或自定义路由组中是否错误使用了throttle，比如拼写错误或引用方式不正确。
• 验证中间件加载：在路由中手动添加throttle:60,1测试，若仍报错，尝试直接使用完整类名\Illuminate\Routing\Middleware\ThrottleRequests::class替代别名，确认是否是别名注册问题。

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