ASP.NET Core 8 Web API部署IIS后无法访问Scalar UI问题

1. 验证Swagger文档可访问性 #

先确认Swagger JSON文件能正常获取：

• 在浏览器访问 你的站点域名/openapi/v1.json，如果返回404，说明Swagger生成或路由配置存在问题，这会直接导致Scalar UI加载失败。
• 检查AddSwaggerGen配置，确保没有遗漏文档生成的必要设置（比如启用XML注释后的路径配置）。

2. 显式指定Swagger文档路径 #

部署到IIS后，站点可能存在虚拟目录或根路径变化，需要给Scalar明确指定Swagger文档的访问地址：

app.MapScalarApiReference(options =>
{
    options.Title = "CPS - API";
    // 根据站点实际路径调整Swagger文档地址
    options.SwaggerEndpoint = "/openapi/v1.json";
});

3. 调整中间件执行顺序 #

中间件顺序会直接影响功能生效，确保UseSwagger和MapScalarApiReference在授权中间件之前执行，且位于路由映射之前：

builder.Services.AddSwaggerGen();

var app = builder.Build();

// 全局启用Swagger和Scalar，不再区分环境
app.UseSwagger(options =>
{
    options.RouteTemplate = "/openapi/{documentName}.json";
});

app.MapScalarApiReference(options =>
{
    options.Title = "CPS - API";
    options.SwaggerEndpoint = "/openapi/v1.json";
});

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

app.MapControllers();

app.Run();

4. 检查IIS站点配置细节 #

• 确保站点的应用程序池设置为.NET CLR版本: 无托管代码，匹配ASP.NET Core应用的运行要求。
• 确认服务器已安装ASP.NET Core Hosting Bundle，这是IIS托管ASP.NET Core应用的必要组件。
• 如果站点使用虚拟目录，需要在UseSwagger的RouteTemplate和SwaggerEndpoint中加入虚拟目录路径，比如虚拟目录为/api，则路径改为/api/openapi/{documentName}.json，SwaggerEndpoint设为/api/openapi/v1.json。

5. 通过浏览器开发者工具排查 #

按F12打开浏览器开发者工具，查看以下内容：

• 控制台标签：检查是否有JS加载错误、跨域报错等信息。
• 网络标签：确认Scalar的静态资源（JS/CSS）、Swagger JSON文件是否返回200状态码，若存在404则调整对应路径配置。

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