最稳妥方式是路由规则+命名空间隔离+中间件校验三者配合：路由需用正则约束version（如v\d+），控制器须显式声明对应命名空间，中间件须白名单校验并早返回非法请求。
ThinkPHP6 用 URL 路径前缀（如 /v1/user）做 API 版本控制，最稳妥的方式是「路由规则 + 控制器命名空间隔离 + 中间件校验」三者配合，而不是只靠路由重写或单纯建子目录。
Route::rule() 匹配 :version 动态参数必须加约束
直接写 Route::rule(':version/:controller/:action', ':version.:controller/:action') 看似简洁，但会导致任意字符串（比如 /abc/xxx）都命中，后续控制器找不到就报 404 或类不存在错误，且无法区分合法版本号。
- 必须给
:version加正则约束，例如[\w]+或更严格地限定为v\d+ - 推荐写法：
Route::rule('v\d+/:controller/:action', ':version.:controller/:action')->pattern(['version' => 'v\d+']) - 注意：
:version在 pattern 中定义后，才能在路由地址中被正确解析并透传到控制器命名空间 - 如果用多应用模式（
think-multi-app），该路由应放在对应应用的route/api.php中，而非全局route/app.php
控制器必须按版本分 namespace，不能只靠目录结构
TP6 不会自动把 v1.User/index 映射到 app\controller\v1\User，除非你显式声明命名空间。光建 app/controller/v1/ 目录没用，类里不写 namespace app\controller\v1;，框架根本找不到这个类。
- 每个版本控制器需独立命名空间，例如：
app\controller\v1\User、app\controller\v2\User - 基础控制器（如
BaseController）建议放在app\BaseController，所有版本控制器都继承它，避免重复逻辑 - 若用多应用，不同版本可拆成不同应用（
app/v1、app/v2），但维护成本高，小项目不推荐 - 别在控制器里手动判断
input('version')再 require 文件——破坏自动加载，也绕过中间件和生命周期
VersionControl 中间件要拦截非法版本并早返回
路由能匹配不等于版本合法。比如用户访问 /v999/user/index，路由照样转发，但你的 v999 控制器根本不存在，最后报错难定位。中间件才是第一道过滤网。
立即学习“PHP免费学习笔记（深入）”；
- 中间件
handle()中从 URL 提取$request->param('version')，检查是否在白名单（如['v1', 'v2']） - 不合法时直接
return json(['msg' => 'Unsupported API version'], 400)，不要throw new HttpException(400)—— 那会进异常处理器，可能被统一 JSON 包装，但状态码易被覆盖 - 中间件注册位置很重要：必须放在路由中间件组里（
middleware.php的'route' => [...]），不能只放全局中间件，否则未匹配路由也会执行，浪费性能 - 别在中间件里修改
$request->path()或伪造参数——TP6 的路由解析已结束，改了也没用
跨域和 JSON 响应需与版本控制解耦
版本控制本身不处理跨域或响应格式，但这两项常被一起配置，容易混淆职责。比如在路由里写 ->allowCrossDomain(...)，看似方便，实则把跨域策略和路由耦合，v2 接口未来要单独设 CORS 就得复制粘贴。
- 跨域应统一用中间件（如
CorsMiddleware）处理，通过header()设置，对所有 API 生效 - JSON 响应统一用
return json($data, $code)，不要依赖模板或echo json_encode()；尤其注意错误分支也要显式设状态码，否则前端拿不到 4xx/5xx - 别在
config/template.php关闭模板引擎来“适配 API”——这会影响异常页面渲染，调试时反而看不到详细报错 - 版本号不应出现在响应头（如
X-API-Version），除非业务强要求；优先靠 URL 和文档约定，减少传输冗余
真正麻烦的不是写几行路由或建几个目录，而是版本升级时控制器方法签名变化、模型字段增减、缓存键迁移这些隐性依赖。URL 版本控制只是入口开关，背后的数据契约、兼容策略、废弃通告机制，才是压垮人的地方。
