ASP.NET Core 实现 API 版本控制，推荐使用官方支持的
Microsoft.AspNetCore.Mvc.Versioning包，它轻量、灵活，与 MVC 深度集成，支持 URL、查询参数、请求头等多种版本标识方式。
安装并启用版本控制服务
在
Program.cs中注册服务并配置基础行为： 通过
AddApiVersioning启用版本控制，设置默认版本（如
1.0）和是否报告支持的版本 可选启用
AssumeDefaultVersionWhenUnspecified = true，让无版本请求默认走 v1 若需返回
api-supported-versions或
api-deprecated-versions响应头，开启
ReportApiVersions = true示例：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
在控制器中声明版本支持
使用
[ApiVersion]特性标注控制器或具体 Action，支持多个版本同时存在： 单个控制器支持多版本：加多个
[ApiVersion("1.0")] 和 [ApiVersion("2.0")]
不同控制器处理不同版本：如 ProductsControllerV1和
ProductsControllerV2，都路由到
/api/products配合
[MapToApiVersion("2.0")] 可将某个 Action 限定只响应 v2 请求
注意：必须为每个版本提供至少一个匹配的 endpoint，否则会返回 400 或 404。
选择版本识别方式（URL / Query / Header）
默认通过请求头
api-version识别，但更常见的是 URL 路径（如
/api/v1/products）或查询参数（如
/api/products?api-version=1.0）： URL 路径：配置
options.ApiVersionReader = new UrlSegmentApiVersionReader();，再用
[Route("api/v{version:apiVersion}/[controller]")]
查询参数：用 new QueryStringApiVersionReader("api-version")
请求头：默认即支持，客户端传 api-version: 2.0也可组合使用，如优先读 URL，降级读 Header
处理弃用与兼容性提示
对已废弃的版本，可通过特性明确标记，并由框架自动注入响应头：
给控制器加[ApiVersion("1.0", Deprecated = true)]
启用 ReportApiVersions = true后，v1 接口响应头会包含
api-deprecated-versions: 1.0客户端可根据该头决定是否提醒用户升级，服务端无需手动拦截或返回特殊状态码
基本上就这些。不复杂但容易忽略细节，比如忘了注册服务、没配路由模板、或多个版本控制器冲突——调试时留意日志里
ApiVersionMatcherPolicy的匹配结果即可。
