H5多版本路由冲突应通过请求入口前置版本识别、接口代理与服务端路径前缀隔离解决，而非前端注解；需统一封装带版本标识的请求方法，动态获取API路径，并在网关/Nginx层按/v1、/v2前缀转发，配合拦截器降级与history模式路径隔离。
直接用自定义注解解决 H5 多版本路由冲突，核心不是写注解本身，而是把版本识别逻辑前置到请求入口，并与路由匹配解耦。H5 端没有后端那样的完整路由注册机制，所以不能照搬 Spring 的 @RequestMapping("/v1/user") 做法——关键在于「请求路径解析 + 版本分流 + 接口代理」三层联动。
注解定义要轻量，只标记版本意图
不建议在前端 JS 层搞复杂注解处理器（不可行）。真正可落地的是：在接口调用层统一封装一个带版本标识的请求方法，用类似 Java 注解风格的配置对象来声明版本需求。例如：
-
定义一个语义化配置对象：
{ version: 'v2', api: '/user/profile' }，它替代传统注解，但作用一致——显式声明本次调用的目标版本 -
禁止硬编码路径：所有接口地址必须通过
apiConfig.get('user.profile')动态获取，而该方法内部根据当前环境、用户权限或本地缓存的activeVersion返回对应路径（如/api/v2/user/profile或/api/v1/user/profile） -
配合构建时注入：在 uni-app 或 Vue 项目中，可通过
process.env.VUE_APP_API_VERSION控制默认版本，再结合运行时动态切换能力，避免打包多套产物
服务端需配合做路径收敛与反向代理
前端注解只是“声明”，真正解决冲突靠服务端路由策略。FastAdmin、ThinkPHP 或 Nginx 层必须支持按前缀隔离版本流量：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 将所有 H5 请求统一打到网关入口（如
/api/xxx），由网关解析路径中的v1、v2段，转发至对应后端集群或模块 - 若使用 Nginx，配置类似：
location ^~ /api/v2/ { proxy_pass http://backend-v2; }location ^~ /api/v1/ { proxy_pass http://backend-v1; } - 避免让 H5 直连不同域名或端口——那会引发跨域和维护混乱；统一域名 + 路径前缀是最轻量、最兼容的方案
拦截器里做版本兜底与降级
当某版本接口临时下线或返回 404，不能让页面白屏或报错。应在请求拦截器中加入版本容错逻辑：
- 首次请求 v2 接口失败（状态码 404 或超时），自动降级为 v1 并重试，同时记录日志供后续分析
- 对关键业务接口（如登录、支付），强制指定最小可用版本，不允许降级，避免数据格式错乱
- 利用 localStorage 缓存最近一次成功响应的版本号，下次打开页面优先尝试该版本，提升首屏成功率
uni-app/H5 侧特别注意 history 模式适配
如果 H5 使用了 history 模式，且后端也用了 FastAdmin 的 /index.php 路由入口，容易出现伪静态冲突——比如访问 /web/v2/user 时被误导向 index.html，导致接口请求也被重写。
- 确保 Nginx/Apache 的重写规则明确排除 API 路径：
rewrite ^/web/(api|static)/.*$ /web/$1/ break; - 前端路由与 API 路由严格分离：H5 页面路由走
/web/xxx，接口统一走/api/vN/xxx，从路径设计上物理隔离 - 开发阶段启用 Chrome 的 Network → Filter → XHR，快速验证接口是否真的发到了正确版本路径
