URL路径版本最稳妥，因不依赖HTTP头字段，调试直接改URL即可切换版本，且兼容Postman、curl、浏览器及缓存代理；请求头版本则易受CORS、CDN、Swagger和前端fetch/Axios限制，常导致406错误。
URL 路径版本（如）是生产环境唯一推荐的方式；请求头版本（）在真实项目中几乎不可用，会卡在 CORS、CDN、Swagger 和前端 fetch/Axios 默认行为上。
为什么 URL 路径版本最稳妥
它不依赖任何 HTTP 头字段，调试时直接改 URL 就能切版本，Postman、curl、浏览器地址栏全支持。缓存代理（如 Nginx、Cloudflare）、日志系统、监控平台都能按路径天然区分版本流量。
关键实操点：
必须配合含
的路由模板，例如：
+
不能同时注册
和
—— 前者贪婪匹配，后者永远不生效
是 MVC 内置约束名，拼错成
会导致 404，不是配置问题，是路由解析失败
未加
的控制器，即使标了
，模型验证和自动 400 响应也会失效，影响版本行为一致性
为什么请求头版本在真实项目中基本跑不通
它要求客户端始终发送正确的
或自定义头（如
），但现实里：
前端
默认不带
头，Axios 也不自动加 vendor MIME 类型
CORS 预检请求（OPTIONS）可能被代理/CDN 拦截或丢弃自定义头
Swagger UI 默认不提供头字段输入框，需额外集成
才能选版本
错误现象典型：Postman 测试正常，但前端调用返回
，且无明确日志指向原因
如何正确启用并声明多版本
两步缺一不可：服务注册 + 控制器显式标注。漏掉任一环节，版本控制就形同虚设。
在
中注册服务（注意顺序：必须在
之后、
之前）：
C知道
CSDN推出的一款AI技术问答工具
下载
控制器写法（必须同时满足三项）：
标注
和
（只写一个则无法响应另一版本）
标注
（
占位符不可少）
标注
（保障版本相关过滤器和绑定行为一致）
若某 Action 仅属于 v2，而控制器默认支持 v1/v2，可用
显式绑定——但它只在控制器已声明
的前提下才生效。
不生效的真正原因
这个特性不是“覆盖版本”，而是“路由注册开关”。如果控制器只标了
，你给某个方法加
，框架压根不会为该方法注册 v2 路由——不是 404，是根本不可达。
常见误用场景：
想用单个控制器支持多版本，却只写
，再靠
控制个别方法升级
控制器类上漏掉
，只在方法上加
路由模板没写
，导致框架无法提取版本号，所有
全部失效
最易被忽略的点：服务注册缺失、路由模板缺占位符、控制器版本声明不全——这三处出错，都不会报编译或启动异常，但版本路由静默退化到默认行为，极难排查。
/api/v1/usersAccept: application/vnd.myapi.v1+jsonMapControllers()v{version:apiVersion}app.MapControllers();[Route("api/v{version:apiVersion}/[controller]")]"api/[controller]""api/v{version:apiVersion}/[controller]"apiVersionv{version:Version}[ApiController][ApiVersion]Acceptapi-version: 1.0fetchAcceptSwashbuckle.AspNetCore.Filters406 Not AcceptableProgram.csAddControllers()Build()builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader(); // 仅启用路径段
});[ApiVersion("1.0")][ApiVersion("2.0")][Route("api/v{version:apiVersion}/[controller]")]{version}[ApiController][MapToApiVersion("2.0")]"2.0"[MapToApiVersion][ApiVersion("1.0")][MapToApiVersion("2.0")][ApiVersion("1.0")][MapToApiVersion("2.0")][ApiVersion("2.0")][MapToApiVersion("2.0")]v{version:apiVersion}[MapToApiVersion]