最稳妥方式是在 routes/api.php 中用 Route::prefix('api/v1') 分组并显式设 as 参数，如 ->as('api.v1.users')，避免中间件或请求头做版本分发，防止 route:list 失效、缓存混乱及 IDE 跳转失败。
API 路由怎么加版本前缀（比如 /api/v1/users）
直接在路由文件里用 prefix 最稳妥，别碰中间件或请求头解析做版本分发——Laravel 原生不支持运行时动态切换路由组版本，硬搞容易让 route:list 失效、缓存混乱、IDE 无法跳转。
常见错误现象：Route [api.v1.users.index] not defined，或者 POST 请求被 405 Method Not Allowed —— 往往是没把 middleware 正确绑定到带前缀的路由组，或者漏了 api 中间件（导致 CSRF 验证失败）。
- 在
routes/api.php里按版本拆成独立Route::prefix()组，每组显式加middleware('api') - 避免嵌套多层
prefix，比如prefix('api')->prefix('v1')，改用单层prefix('api/v1')，减少路由编译歧义 - 版本号建议用
v1、v2字符串，别用数字1或2，否则和 Laravel 的资源路由参数冲突（如{id}可能误匹配）
如何让不同 API 版本共用模型但隔离控制器和验证逻辑
版本差异通常不在数据结构，而在字段可见性、参数校验规则、响应格式。硬拷贝控制器或重复写 Request 类，后续维护成本爆炸。
使用场景：v1 返回 created_at 时间戳，v2 改成 ISO8601 字符串；v1 允许空字符串用户名，v2 要求非空且带正则校验。
- 控制器保持独立（
App\Http\Controllers\Api\V1\UserController和V2\UserController），但复用同一个模型User -
FormRequest类也按版本分离（StoreUserRequestV1/StoreUserRequestV2），不要试图在单个rules()方法里 if-else 判版本 - 响应 DTO 或资源类（
UserResource）同样分版本，避免在toArray()里写if (request()->routeIs('api.v2.*'))—— 路由信息在资源类里不可靠，且破坏可测试性
Route::apiResource 在带版本前缀时为什么总丢方法
不是 Laravel Bug，是前缀和资源路由动词映射没对齐。比如 Route::prefix('api/v1')->group(...) 里用 apiResource('users')，生成的 index 路由名是 users.index，而不是预期的 api.v1.users.index，导致命名空间混乱、生成 URL 失败。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
性能影响：路由缓存时若名称不规范，php artisan route:cache 可能静默失败，线上 404 无提示。
- 必须给每个
apiResource显式指定as参数，例如：->as('api.v1.users') - 不要依赖默认命名，哪怕只有一版 API —— 后续升级时加版本会卡在这一步
- 检查
php artisan route:list输出中 Name 列是否含完整前缀，没出现就说明as没生效
要不要用第三方包（比如 dingo/api 或 cloudcreativity/laravel-json-api）
除非你明确需要自动内容协商（Accept header 解析）、JSON:API 规范强制校验、或跨版本字段自动转换，否则别引入。这些包在 Laravel 9+ 之后和原生路由机制耦合变差，升级常出兼容问题。
容易踩的坑：dingo/api 会接管全部 /api/* 请求，绕过 Laravel 的中间件栈，导致自定义日志、权限中间件失效；它的版本控制走请求头，和前端实际部署的 Nginx 转发规则冲突概率高。
- 纯前缀路由 + 手动分组足够覆盖 95% 的 API 版本需求
- 如果真要 Accept 头版本化，优先用简单中间件读取
request()->header('Accept')，再重定向到对应api/v1/*路由，比换整套路由系统轻量得多 - 注意：Laravel 自己的
Route::version方法并不存在 —— 这是个高频误解，搜索结果里很多过时文章写的伪代码
版本号一旦写进路由前缀，就等于向客户端承诺长期维护。删 v1 前得确认所有调用方已切走，HTTP 301 重定向也救不了 header 里带 v1 的旧 SDK。这点比技术实现更难收场。
