核心问题是路由分组未用固定字符串前缀、控制器命名空间与目录结构不一致、中间件未按分组链式绑定；正确做法是Route::group('api/v1')明确分组、严格匹配namespace和文件路径、中间件在分组内链式调用，并在响应中硬编码version字段。
ThinkPHP接口版本控制出现冲突，核心问题往往不在“能不能做”，而在于路由设计、控制器组织和中间件绑定这三个环节没对齐。常见冲突包括：v1/v2请求进错控制器、版本参数取不到、中间件没生效、上线后全404等。解决关键不是堆逻辑，而是让版本标识在路由层干净落地、控制器层严格隔离、中间件层精准绑定。
路由配置必须用分组前缀，别碰变量路由
直接写 Route::get('api/v1/user', ...) 或 Route::rule(':version/user', ...) 是冲突高发区。前者维护成本爆炸，后者漏写 ->pattern(['version' => 'v[12]']) 会导致 v10、v999 全部匹配到 v1 规则，且 :version 不自动注入控制器，还得手动 input('version') 判断，徒增分支。
- 正确做法是用字符串字面量分组：
Route::group('api/v1', function () { Route::get('user', 'api/v1.User/read'); }); -
Route::group()第一个参数必须是固定字符串（如'api/v1'），不能是变量或配置项，否则路由缓存生成失败，开发环境正常、上线就 404 - 多个版本统一前缀，避免重复定义；TP6.1+ 支持 prefix 自动注入闭包，但需确保命名空间与目录结构完全一致
控制器命名空间与目录结构必须严丝合缝
路由里写的 api/v1.User/read，对应的就是 app/controller/api/v1/User.php，且文件首行命名空间必须是 namespace app\controller\api\v1;。大小写、路径层级、类名、文件名，错一个就 500。
- Linux 下
v1和V1是不同目录，Windows 可能不报错但线上挂掉 - 类名必须是
User，不是UserController——除非你在路由里明确写成api/v1.UserController/read - 类必须继承 BaseController，且方法名要与路由 action 一致（如
read()对应 GET /user/:id）
中间件必须按分组绑定，禁止全局注册或条件挂载
有人在 middleware.php 里写 ['api/v1' => [JwtAuth::class]]，结果中间件完全不触发——因为 ThinkPHP 不解析 URL 字符串匹配中间件，只认路由定义时的规则名或分组名。
立即学习“PHP免费学习笔记（深入）”；
- 正确方式是在分组内链式绑定：
Route::group('api/v2')->middleware(JwtAuth::class)->group(function () { ... }); - v1 不需要鉴权、v2 需要？那就分开写两个分组，不要试图在中间件里做
if ($request->path() === '/api/v2') {...} - 跨域、限流、日志等中间件，也按版本分组独立配置，避免老版本被新中间件逻辑干扰
响应体必须显式返回 version 字段
即使 URL 已带 /v2/，也要在 JSON 响应里写死 "version": "v2"。这不是冗余，而是给前端、监控、网关提供可验证依据。比如某次发布后发现小程序调的是 /v1 接口，但响应却写了 "version": "v2"，立刻能定位是反向代理转发错了。
- 该字段由服务端硬编码输出，不能从请求头或参数读取，防止伪造或遗漏
- 建议在基础控制器的
success()方法中统一注入：return json(['code'=>0, 'data'=>$data, 'version'=>'v2']); - 数据库变更、字段增减等兼容性处理，也应围绕这个 version 字段做数据组装（如 Resource 类），而非在控制器里 if-else 分支
