Route::prefix() 是 Laravel API 版本控制最稳妥方式，需显式加 middleware('api')、严格匹配命名空间、规范路由别名、物理隔离控制器与资源类，并验证 route:list 输出。
直接用 Route::prefix() 做 API 版本控制是 Laravel 里最稳妥、最可控的方式，不依赖第三方包，也不引入运行时解析开销。它把版本语义固化在 URL 路径上，让路由定义清晰、调试直观、缓存可靠、文档可生成。
Route::prefix() 必须配合 middleware('api') 显式声明
常见错误是只加前缀却漏掉中间件，导致 v1/v2 路由走错中间件栈——比如 CSRF 验证失败（419）、认证跳转登录页、限流不生效等。
-
Route::prefix('v1')本身不继承任何中间件，必须显式写->middleware('api') - 别指望 RouteServiceProvider 的全局
middleware('api')会自动透传到 prefix 组内 - 如果用了自定义中间件如
EnsureApiVersion，也得一起写进 middleware 数组里，例如->middleware(['api', 'ensure.api.version']) - 漏掉
'api'是线上 405 或 419 的高频原因，尤其 POST/PUT 请求
命名空间(namespace) 和控制器路径要严格对应
版本控制器必须放在匹配的命名空间下，否则 php artisan route:list 会报 Class not found，IDE 也无法跳转。
- 推荐结构：
App\Http\Controllers\Api\V1\UserController对应->namespace('App\Http\Controllers\Api\V1') - 别用
App\Http\Controllers\V1这类扁平命名空间，容易和 web 控制器冲突 - 资源路由（
Route::apiResource()）必须加->as('api.v1.users')，否则生成的路由名是users.index，不是你预期的api.v1.users.index，URL 生成（route()）和测试都会出问题 - 检查
php artisan route:list输出的 Name 列是否含完整前缀，没出现就说明as没生效
v1 和 v2 控制器必须物理隔离，禁止 if-else 判版本
把 if ($request->routeIs('api.v2.*')) 写进控制器或 Resource 类里，短期省事，长期难测、难维护、难缓存。
- 字段增减、校验规则变化、响应格式差异，都该由独立的
V1\UserResource和V2\UserResource承担 - FormRequest 也要分版本，
StoreUserRequestV1和StoreUserRequestV2各自定义rules() - 模型层尽量复用，但控制器和资源类绝不混用——这是边界，越模糊，v3 上线时重构成本越高
- 中间件里做版本兜底（如 v2 请求 fallback 到 v1 响应）可以，但控制器里不做逻辑分支
真正容易被忽略的是路由缓存：如果 as 名不规范或 namespace 错位，php artisan route:cache 可能静默失败，上线后大量 404 却无日志提示。每次加新版本，先跑一遍 route:list 确认 Name 和 Action 列都对得上，比事后 debug 快十倍。
