添加aspnet-api-versioning后，Razor Pages请求中UrlHelper无法生成API控制器路由

我经手过不少类似的场景：当给ASP.NET Core项目同时添加Razor Pages和aspnet-api-versioning组件后，用IUrlHelper生成API控制器的命名路由时会失败，但纯API项目里却完全正常。结合你给出的示例代码，我整理了具体的原因和解决办法：

问题场景还原 #

你的API控制器代码大概是这样的（补全了示例里的省略部分）：

[Route("api/[controller]")]
public class ValuesController : Controller
{
    public const string GetValues = "GetValues";
    public const string GetValuesById = "GetValuesById";
    public static string[] Values = new[] { "value1", "value2", "value3" };

    // GET api/values
    [HttpGet(Name = GetValues)]
    public IEnumerable<object> Get()
    {
        var result = new List<object>();
        for(int index = 0; index < Values.Length; index++)
        {
            result.Add(new { Id = index + 1, Value = Values[index] });
        }
        return result;
    }

    // GET api/values/5
    [HttpGet("{id}", Name = GetValuesById)]
    public IActionResult Get(int id)
    {
        if(id < 1 || id > Values.Length)
            return NotFound();
        
        return Ok(new { Id = id, Value = Values[id - 1] });
    }
}

在纯API项目里，用Url.Link(GetValues, null)能正常生成/api/values，但放到带Razor Pages的项目里，调用同样的方法却返回null或者生成错误的链接。

问题根源 #

核心原因是aspnet-api-versioning给API路由添加了版本约束，但Razor Pages的UrlHelper属于UI上下文，默认不会携带API版本信息——而API控制器的路由现在需要这个版本参数才能匹配成功。纯API项目里所有请求都是API请求，UrlHelper会自动继承当前请求的版本上下文，所以没问题，但Razor Pages请求没有这个上下文，自然匹配不到路由。

具体解决步骤 #

1. 确认API版本控制的基础配置 #

首先确保Program.cs里的API版本配置是完整的，比如：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    // 如果用URL路径传版本，启用这个；用Header的话换对应的Reader
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

// 可选但推荐：添加版本化API探索器，方便后续文档生成
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

2. 生成路由时显式传入API版本参数 #

这是最关键的一步！在Razor Pages的cshtml或PageModel里，必须主动提供apiVersion参数：

在cshtml视图中：

<!-- 生成GetValues路由的链接 -->
<a asp-route="@ValuesController.GetValues" asp-route-api-version="1.0">查看所有值</a>

<!-- 生成GetValuesById路由的链接，同时传入id参数 -->
<a asp-route="@ValuesController.GetValuesById" asp-route-id="1" asp-route-api-version="1.0">查看值1</a>

在PageModel中：

public class IndexModel : PageModel
{
    private readonly IUrlHelper _urlHelper;

    public IndexModel(IUrlHelper urlHelper)
    {
        _urlHelper = urlHelper;
    }

    public string AllValuesUrl { get; set; }
    public string SingleValueUrl { get; set; }

    public void OnGet()
    {
        // 显式指定apiVersion参数
        AllValuesUrl = _urlHelper.RouteUrl(ValuesController.GetValues, new { apiVersion = "1.0" });
        SingleValueUrl = _urlHelper.RouteUrl(ValuesController.GetValuesById, new { id = 1, apiVersion = "1.0" });
    }
}

3. 给API控制器的路由显式添加版本参数（可选但更清晰） #

如果希望路由更明确，可以修改API控制器的路由模板，把版本参数写进去：

[Route("api/v{apiVersion:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class ValuesController : Controller
{
    // ... 原有代码不变
}

这样路由会变成/api/v1/values，生成链接时同样需要传入apiVersion参数，可读性更强。

4. 排查路由冲突（兜底检查） #

确保Razor Pages的自定义路由没有和API路由冲突，比如不要把Razor Pages的路由模板设为api/{page}，避免覆盖API的路由规则。

总结 #

本质上就是Razor Pages和API的上下文不共享版本信息，所以必须显式传递版本参数才能让UrlHelper匹配到API的路由。按照上面的步骤调整后，应该就能正常生成API链接了。

内容的提问来源于stack exchange，提问作者Johnathon Sullinger