ThinkPHP版本路由应使用Route::group()统一声明前缀，避免中间件分发和路径硬编码；版本差异应在控制器层协议适配，中间件需按分组绑定；注解路由须配置多controller_path并确保命名空间规范。
ThinkPHP 路由怎么支持 v1/v2 版本路径前缀
直接在 route/app.php 里用分组加前缀是最稳的，别碰中间件做版本路由分发——那会绕过路由缓存，也容易和跨域、鉴权等中间件顺序冲突。
常见错误是把版本号写死在每个接口路由里，比如 api/v1/user 和 api/v2/user 分开注册，结果维护时漏改一个就出问题。
- 用
Route::group()统一声明前缀：Route::group('api/v1', function () { Route::get('user', 'v1.User/get'); }); - 多个版本共用同一控制器方法？可以传参数：
v1.User/get?version=v1，但不推荐——语义不清，也不利于文档生成和网关识别 - 注意：TP6.1+ 支持
prefix参数自动注入到闭包或类方法，但需开启route_annotation且控制器命名空间要匹配，否则__invoke不触发
如何让 v2 接口兼容 v1 的参数结构但返回新字段
不是靠路由转发，而是靠控制器层做「协议适配」。版本差异本质是输入/输出契约变化，路由只负责分发，不该承担转换逻辑。
典型坑是用中间件统一拦截 v2 请求然后改 input() 数组——这会污染原始请求，导致日志、审计、重放校验全乱套。
立即学习“PHP免费学习笔记（深入）”；
- 在
v2.User控制器里调用v1.User的业务方法，再包装响应：$data = (new v1\User())->get(); return json(['code'=>0, 'data'=>$data, 'v2_extra'=>'ok']); - 如果字段名冲突（比如 v1 返回
user_name，v2 要name），用数组映射比硬编码 if-else 更易维护：Arr::only($data, ['id', 'user_name']) → ['id','name'] - TP 自带的
think\facade\Request在不同版本控制器中行为一致，但注意input('page/d', 1)这类默认值定义必须显式保留，v2 不该隐式覆盖 v1 的默认逻辑
升级后老版本接口还能不能走新中间件（如 JWT 鉴权）
能，但必须按路由分组绑定，不能全局注册。TP 的中间件绑定粒度是「路由规则」，不是「URL 前缀字符串」。
有人试过在 middleware.php 里写 ['api/v1'=>[JwtAuth::class]]，结果发现没生效——因为 TP 不解析路径字符串做中间件匹配，只认路由定义时的规则名或分组名。
- 正确做法：在分组内链式绑定：
Route::group('api/v1', function () { /* ... */ })->middleware(JwtAuth::class); - 如果 v1 不需要鉴权而 v2 需要，就分开写：
Route::group('api/v2')->middleware(JwtAuth::class)，别试图用条件判断动态挂载 - 注意中间件执行顺序：TP 是先跑路由绑定的中间件，再跑全局中间件。如果你在全局写了 CORS，又在 v2 分组里写了 JWT，那预检请求（OPTIONS）可能被 CORS 拦截前就卡在 JWT 的 token 解析上
为什么 route:clear 后 v2 接口 404，但 v1 正常
大概率是路由缓存没刷全，或者注解路由扫描路径没包含 v2 对应的控制器目录。
TP6 默认只扫描 app/controller，如果你把 v2 控制器放在 app/v2/controller，又没在 config/route.php 里配 controller_path，那注解路由根本不会读它。
- 运行
php think route:clear后，立刻跟一句php think route:list看 v2 路由是否在列表里 - 检查
config/route.php中annotation配置项：'controller_path' => [app_path('controller'), app_path('v2/controller')] - 别信 IDE 的文件索引——TP 注解扫描依赖
ReflectionClass，如果 v2 控制器类名没按 PSR-4 命名（比如少了v2\命名空间），route:list就看不到它
接口版本化最麻烦的从来不是路由怎么写，而是当 v3 上线、v1 下线时，你得同时维护三套输入校验规则、两套数据库字段映射、一套共享的 service 层——这些没法靠路由配置解决，得从一开始就把版本契约拆进独立的 Validate 类和 Dto 类里。
