如何正确配置.NET 6 Web API的URL路径前缀解决404问题

问题原因 #

app.UsePathBase("/test") 生效的核心要求是中间件顺序必须正确，出现仅Swagger生效、接口404的问题，90%是因为把UsePathBase放到了路由相关中间件的后面，路由匹配完成后才执行路径基址配置，自然无法匹配到接口；另外也可能是手动给路由重复加了/test前缀导致匹配失败。

正确配置步骤 #

1. 调整Program.cs中间件顺序，将UsePathBase放在路由、控制器映射、静态资源、Swagger等所有业务中间件之前（仅可放在全局异常处理中间件之后），参考如下最小可运行配置：

var builder = WebApplication.CreateBuilder(args);

// 服务注册部分无需修改，保持原有AddControllers、AddSwaggerGen等配置即可
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// 全局异常处理中间件如果有，放在最前面即可
// app.UseExceptionHandler("/Error");

// 关键：PathBase配置必须放在所有其他业务中间件之前
app.UsePathBase("/test");

// 后续中间件保持原有顺序无需修改
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // Swagger无需单独配置路由前缀，会自动适配/test基址，访问地址为/test/swagger
}

app.UseHttpsRedirection();
app.UseAuthorization();

// 控制器映射不要额外加路由前缀
app.MapControllers();

app.Run();

2. 排查冗余配置
   • 不要在控制器的[Route]特性、最小API的Map规则里手动添加/test前缀。UsePathBase的逻辑是自动剥离请求路径中的/test前缀，将剩余路径交给原有路由规则匹配，手动加前缀会导致匹配路径重复，出现404。
   • 如果服务部署在Nginx、IIS等反向代理后，检查代理转发规则：如果代理已经将/test前缀从请求路径中剥离再转发到服务，服务端无需再配置UsePathBase；如果代理转发全路径，才需要保留该配置。
   • 测试时确认请求地址正确：原有接口地址https://localhost:7027/[controller]，配置后正确地址为https://localhost:7027/test/[controller]，注意不要多写或少写路径分隔符。

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