ASP.NET Core 6部署IIS后Swagger UI出现页面未找到错误

问题情况 #

• 站点已发布至D:\APIsite并配置IIS，绑定规则：http 5139、https 7003 指向127.0.0.1
• 本地调试或直接运行时，访问https://localhost:7003/index.html可正常打开Swagger UI；部署到IIS后，访问https://127.0.0.1:7003或对应Swagger路径均返回“页面未找到”
• 授权流程正常，服务器上其他ASP.NET应用运行无异常，已尝试Debug和Release两种发布配置

相关代码与配置 #

Program.cs #

var builder = WebApplication.CreateBuilder(args);

Log.Logger = new LoggerConfiguration().WriteTo.File(new MyOwnCompactJsonFormatter(), "API_Log.txt").CreateLogger();

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();

builder.Services.AddSingleton<CheckPointMetraContext>();
builder.Services.AddSingleton<CheckPointPackagingContext>();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
    });

});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    app.UseSwagger(c => { c.SerializeAsV2 = true; });
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = string.Empty;
    });
}

app.UseAuthorization();

app.MapControllers();

app.UseRouting();

Log.Logger.Information("API http://localhost:5139/swagger/index.html");

app.Run();

launchSettings.json #

{
  
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:31124",
      "sslPort": 44300
    }
  },
  "profiles": {
    "TestApp": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
     
      "applicationUrl": "https://localhost:7003;http://localhost:5139",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

IIS绑定信息 #

http   5139 127.0.0.1
https  7003 127.0.0.1

解决方法 #

1. 调整Swagger的环境启用规则 #

默认IIS部署使用Production环境，而原代码仅在Development环境加载Swagger，需修改代码让目标环境也启用Swagger：

• 强制启用（适合测试场景）：直接移除环境判断，保留Swagger相关中间件调用
• 指定多环境启用：修改判断条件为包含目标环境，示例：

if (app.Environment.IsDevelopment() || app.Environment.IsProduction())
{
    app.UseSwagger(c => { c.SerializeAsV2 = true; });
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = string.Empty;
    });
}

2. 修正中间件顺序 #

原代码中app.UseRouting()放在app.MapControllers()之后，违反ASP.NET Core中间件执行顺序要求，正确顺序应为：

app.UseRouting();
app.UseAuthorization();
app.MapControllers();

3. 配置IIS站点的环境变量（可选） #

若要保留原代码的Development环境判断，需在IIS中配置站点环境变量：

1. 打开站点的「配置编辑器」
2. 定位到system.webServer/aspNetCore节点
3. 编辑environmentVariables，添加或修改ASPNETCORE_ENVIRONMENT为Development

4. 验证Swagger JSON路径 #

部署后直接访问https://127.0.0.1:7003/swagger/v1/swagger.json，若返回404，说明Swagger未正常生成，需检查环境配置和代码注册逻辑是否生效。

内容的提问来源于stack exchange，提问作者L-sher