推荐使用 Microsoft.AspNetCore.Mvc.Versioning 包实现 ASP.NET Core API 版本控制，支持 URL、查询参数、请求头等多种版本标识方式，需在 Program.cs 中注册服务并配置默认版本、弃用提示等，控制器通过 [ApiVersion] 特性声明版本支持。

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，支持多个版本同时存在：

Microsoft Skill Creator

使用 Learn MCP 工具为 Microsoft 技术创建代理技能。当用户想要创建教授代理任何 Microsoft 技术的技能时使用。

下载

• 单个控制器支持多版本：加多个 [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 的匹配结果即可。