AspnetCore 3.1 API配置URI段版本控制后v2返回UnsupportedApiVersion

你遇到的问题是URL段版本读取配置和路由模板不匹配导致的，按以下步骤修正即可： #

核心修正点 #

1. 匹配版本读取器与路由参数名 #

UrlSegmentApiVersionReader 默认会从名为 apiVersion 的路由参数中读取版本号，如果你的控制器路由模板中版本占位符用的是version（比如路由写为api/v{version}/[controller]），需要在构造读取器时显式指定参数名：

// ApdApiExtensions.cs中的配置改为
options.ApiVersionReader = new UrlSegmentApiVersionReader("version");

如果你的路由模板本身就用了apiVersion作为参数名（api/v{apiVersion:apiVersion}/[controller]），则用默认无参构造即可。

2. 开启版本替换配置 #

在注册版本化API探索器的配置中，必须开启SubstituteApiVersionInUrl，确保路由中的版本占位符能被正确识别、替换：

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader("version"); // 按需传参数名
    options.ReportApiVersions = true;
})
.AddControllers()
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    // 必须开启该配置
    options.SubstituteApiVersionInUrl = true;
});

3. 校验控制器特性配置 #

确保不同版本的控制器都正确标注了[ApiVersion]和路由特性，示例正确配置：

// v1控制器
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class RecordsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok("v1 接口返回");
}

// v2控制器
[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class RecordsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok("v2 接口返回");
}

原理说明 #

你注释版本读取器配置时能正常访问，是因为默认的版本读取器同时支持查询参数和路由段两种读取方式，只要两个地方的版本一致就能匹配。当你切换为仅URL段读取后，由于参数名不匹配/路由替换配置缺失，服务无法从URL段中读取到正确的版本号，会默认回退到v1版本，导致v2路径的请求匹配不到对应接口，返回不支持的版本错误。

内容的提问来源于stack exchange，提问作者Nathan Kamenar