部署至本地文件的ASP.NET Web API在IIS运行报404错误如何解决

按优先级从高到低排查，覆盖绝大多数常见场景：

• 第一优先级检查Swagger环境限制配置
  官方项目模板默认Swagger仅在开发环境加载，.NET 6+项目检查Program.cs，.NET 5及更早版本检查Startup.cs，会看到类似if (app.Environment.IsDevelopment())的判断块，Swagger中间件和Swagger UI的加载代码全在这个块里。IIS部署默认运行在生产环境，根本不会加载Swagger相关路由，访问自然404。可以临时移除环境判断，或者补充生产环境的加载逻辑，修改后重新发布即可。
• 第二优先级检查服务器运行时依赖
  如果部署的是.NET Core/.NET 5+版本项目，服务器必须安装对应版本的ASP.NET Core Hosting Bundle，没装的话IIS无法将请求转发给.NET运行时，不止Swagger，所有接口都会返回404。安装完成后记得执行iisreset重启IIS生效。
  如果是.NET Framework版本的Web API，确认应用程序池对应CLR版本选择正确，且IIS已经安装对应版本的ASP.NET运行时组件。
• 第三优先级检查IIS基础配置
  • .NET Core/.NET 5+项目的应用程序池.NET CLR版本要选「无托管代码」，托管管道模式选集成
  • 网站物理路径必须指向发布产物的根目录，不要指向bin文件夹或者上一层目录
  • 给发布目录分配IIS_IUSRS用户的读取、执行权限，权限不足也会导致资源加载失败返回404
• 第四优先级检查发布配置正确性
  • 如果发布时开启了单文件发布、程序集裁剪，先关闭这两个选项重新发布，裁剪逻辑很容易误删Swagger相关依赖文件
  • 确认项目配置生成的XML注释文件被输出到发布目录，Swagger加载找不到注释文件时也可能触发异常
  • 检查发布后自动生成的web.config文件，aspNetCore节点下的processPath配置正确：框架依赖模式下默认值为dotnet，需要确保系统环境变量能正常找到dotnet命令；自包含部署模式下要指向项目对应的exe文件
• 第五优先级检查访问路径和路由配置
  • 如果项目部署在IIS的虚拟目录下（比如挂在/app二级路径），访问Swagger需要带上虚拟目录前缀，正确地址格式为http://你的域名/虚拟目录名/swagger/index.html，直接访问/swagger会因为路径不匹配返回404
  • .NET Framework版本的Web API需要检查是否配置了无扩展名请求处理，老版本IIS默认不会把无后缀的API请求转给ASP.NET处理，在web.config的system.webServer节点下补充如下配置即可：

<handlers>
  <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
  <remove name="OPTIONSVerbHandler" />
  <remove name="TRACEVerbHandler" />
  <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
</handlers>

快速定位问题技巧：在部署服务器上进入发布文件根目录，打开命令行执行dotnet 你的项目入口dll名.dll，直接通过Kestrel启动项目，访问http://localhost:5000/swagger测试。如果此时能正常打开，问题100%出在IIS配置或者Hosting Bundle安装上；如果Kestrel启动后也无法访问，就是项目本身的配置、发布流程有问题，和IIS无关。

内容的提问来源于stack exchange，提问作者O.G