Laravel升级后路由404主因是RouteServiceProvider中mapApiRoutes()未正确注册api前缀或中间件组，导致routes/api.php未被加载；需运行php artisan route:list验证路由是否真实注册，并确认mapApiRoutes()严格匹配prefix('api')->middleware('api')->group(base_path('routes/api.php'))。
升级 Laravel 后原本能访问的 API 或 Web 路由突然返回 404，不是缓存没清干净，而是框架底层路由注册机制、中间件绑定逻辑或 RouteServiceProvider 加载顺序发生了变更，旧版写法在新版中已被弃用或行为不兼容。
确认路由是否真实加载
运行 php artisan route:list 查看当前内存中实际注册的路由表——这是唯一反映框架真实状态的权威依据。
若目标路由完全不在列表里，说明它根本没被加载；若存在但 URI 显示为 GET /data（而非 GET api/data），说明 routes/api.php 没走 api 前缀逻辑，大概率是 RouteServiceProvider 中 mapApiRoutes() 方法被意外覆盖或未调用。
执行 php artisan route:list --path=api 过滤出所有含 api 的路由，快速验证 API 路由是否挂载成功。
检查 RouteServiceProvider 是否适配新版结构
Laravel 12 起强化了路由编译机制，mapApiRoutes() 必须显式调用 Route::prefix('api') 并绑定 api 中间件组，否则路由不会自动加前缀。
打开 app/Providers/RouteServiceProvider.php，确认 mapApiRoutes() 方法内容如下：
【必须严格匹配】：Route::prefix('api')->middleware('api')->namespace($this->namespace)->group(base_path('routes/api.php'));
⚠️ 若你此前为支持多版本 API 自定义了 prefix('{version}/api')，Laravel 12 默认不再兼容该写法——更长的前缀必须手动注册在通用 prefix('api') 之前，否则会被截断匹配。
验证中间件组是否生效
方法一：检查 app/Http/Kernel.php 中 $middlewareGroups 数组是否存在名为 api 的键，且其值包含 EnsureFrontendRequestsAreStateful::class、ThrottleRequests::class 等基础中间件。
方法二：在 routes/api.php 开头临时添加一条测试路由：Route::get('/ping', fn() => 'ok')->name('api.ping');，然后运行 php artisan route:list --name=api.ping，观察 Middleware 列是否显示 api。若为空，说明中间件组未注入。
方法三：直接在浏览器访问 http://localhost:8000/api/ping，若返回 404 且 route:list 中无该路由，证明 api 中间件组未激活，routes/api.php 实际未被加载。
排查模型绑定与参数解析变更
第一步：确认控制器方法签名是否仍使用隐式绑定类型提示，例如 function show(Post $post)。
第二步：检查对应模型类 App\Models\Post 是否声明了 protected $keyType = 'string' ——Laravel 12 对 UUID 主键的隐式绑定默认启用严格类型校验，若未设置，会静默跳过绑定，导致路由匹配失败后 fallback 到下一个路由，最终 404。
第三步：若 URL 含可选参数如 {slug?}，需确认是否在路由定义后追加了 ->defaults('slug', 'home')，新版编译器对未设默认值的可选参数不再自动补空字符串，直接判定不匹配。
清除残留缓存并重启服务
① 清除路由缓存：php artisan route:clear
② 清除配置缓存：php artisan config:clear
③ 清除视图缓存：php artisan view:clear
④ 重启开发服务器：php artisan serve（不要复用旧进程）
这一步操作起来很简单，直接把终端关掉重开就行。但注意：若项目部署在 Nginx/Apache 上，还需同步检查服务器配置是否仍将 public 目录设为 root，升级后部分环境模板会重置文档根路径到项目根目录，导致所有请求绕过 public/index.php，直接 404。
