laravel 11 默认不自动加载 routes/api.php，导致 api 路由 404；需执行 php artisan install:api 或在 bootstrap/app.php 中显式配置 ->withrouting(api: __dir__.'/../routes/api.php') 并重启服务。
升级到 Laravel 11 后，路由 404 不是代码写错了，而是框架默认行为变了——特别是 api.php 默认不再自动加载，这是 Laravel 11 的关键变更，也是接口 404 最常见的原因。
确认 api.php 是否被启用
Laravel 11 开始，routes/api.php 不再由框架默认注册。即使文件存在、路由定义正确，php artisan route:list 也不会显示任何 API 路由，浏览器访问直接 404。
- 运行命令启用：
php artisan install:api（官方推荐方式） - 或手动在
bootstrap/app.php中补上路由注册逻辑（Laravel 11+ 使用函数式引导）：->withRouting(web: __DIR__.'/../routes/web.php',api: __DIR__.'/../routes/api.php', // ← 这行必须显式添加commands: __DIR__.'/../routes/console.php',health: '/up')
检查路由是否真正加载
别只看文件有没有写，要看 Laravel 是否真读进去了：
- 执行
php artisan route:clear清除旧缓存 - 再运行
php artisan route:list --compact - 如果输出里完全没出现
/api/xxx，说明api.php没被引入，不是控制器或方法的问题 - 若列表里有但访问仍 404，检查请求 URL 是否带
/api前缀（Laravel 默认为/api/*，不能漏）
命名空间与控制器调用写法更新
Laravel 10+ 已彻底弃用字符串式控制器写法，Laravel 11 继续强化此规则：
- ❌ 错误写法：
Route::get('/users', 'UserController@index') - ✅ 正确写法：顶部
use App\Http\Controllers\UserController;，然后写成[UserController::class, 'index'] - API 路由通常放在
routes/api.php，它默认使用api中间件组，不带 session/CSRF；若你误把 Web 路由逻辑（如需登录态）写进这里，也可能因中间件拒绝而静默 404
开发服务器必须重启
php artisan serve 不监听 PHP 文件变化。改完 api.php 或 app.php 后：
- 按
Ctrl+C终止当前服务 - 重新运行
php artisan serve - 否则即使配置已生效，服务器仍跑着旧的路由快照
