ASP.NET Core 9集成Scalar遇404错误，API方法未显示求助

排查步骤： #

1. 确认Scalar包安装到位 #

• 检查项目是否安装了Scalar.AspNetCore NuGet包，版本要适配ASP.NET Core 9（直接用最新稳定版即可）。可以在Package Manager Console执行：

  Install-Package Scalar.AspNetCore
  

  或者打开.csproj文件，确认存在以下引用：

  <PackageReference Include="Scalar.AspNetCore" Version="x.x.x" />
  

2. 核对OpenAPI端点配置 #

• 确保Program.cs里的OpenAPI和Scalar配置正确，重点确认Scalar指向的OpenAPI文档路径与实际一致：

  var builder = WebApplication.CreateBuilder(args);
  
  // 注册Swagger生成服务
  builder.Services.AddEndpointsApiExplorer();
  builder.Services.AddSwaggerGen();
  
  var app = builder.Build();
  
  // 启用Swagger生成OpenAPI文档
  app.UseSwagger();
  
  // 配置Scalar，指定OpenAPI文档路由
  app.MapScalarApiReference(options =>
  {
      options.OpenApiRoute = "/swagger/v1/swagger.json";
  });
  
  app.Run();
  

  先手动访问配置的/swagger/v1/swagger.json路径，能正常返回JSON文档才说明OpenAPI配置无问题。

3. 检查静态文件中间件 #

• Scalar依赖静态资源，必须确保UseStaticFiles()中间件在Scalar配置之前启用，顺序不能颠倒：

  app.UseStaticFiles(); // 这行要放在MapScalarApiReference之前
  
  app.MapScalarApiReference(...);
  

  如果自定义了静态资源路径，需确认Scalar的静态文件被正确映射到项目中。

4. 清理缓存重新生成 #

• 删除项目的bin、obj目录，重启Visual Studio后重新生成解决方案，避免旧缓存导致资源缺失。
• 浏览器按Ctrl+Shift+R强制刷新，清除前端缓存，确保加载最新的Scalar资源。

5. 排查路由冲突 #

• 检查是否有自定义路由规则或中间件拦截了/scalar/**开头的请求，比如全局路由模板、权限中间件提前返回404。

6. 验证API是否被Swagger正确发现 #

• 先访问原生Swagger界面（比如/swagger），查看所有API方法能否正常显示。如果Swagger里也没有API，说明问题出在OpenAPI配置本身——检查控制器是否添加了[ApiController]、[Route]属性，或者端点路由是否正确注册。

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