.NET 5下ASP.NET Core Web API部署至Azure后报404的排查解决

先核对应用服务的基础运行时配置 #

• 进入对应App Service的「配置-常规设置」页面，确认运行时栈明确选择**.NET 5 (Out-of-process)**，不能错选其他语言栈，也不要沿用默认的.NET Core 3.1、.NET 6+配置。.NET 5在Azure上不支持In-process宿主模型，选错模型会直接导致应用无法被IIS启动，所有路径统一返回404，和代码是否正确完全无关。修改配置后必须点保存触发应用完整重启，仅做配置修改不重启不会生效。
• 确认.NET 5早期访问的实际生效范围：不要只在订阅层面开启早期访问开关，要确认开关权限没有被应用服务的策略覆盖，避免出现“订阅开了开关，但应用本身拿不到.NET 5运行时”的空转情况。

校验发布包的结构完整性 #

• 打开本地发布输出的根目录，确认必须存在web.config、应用主dll、hosting.ini三类核心文件。缺失web.config的发布包部署后，Kestrel进程根本不会被启动，所有请求都会被IIS按照静态文件规则处理，哪怕你写了正确的控制器路由，也会因为应用没启动返回404。
• 检查web.config内的启动参数路径：框架依赖部署场景下，processPath要指向全局dotnet程序，启动参数要对应.\你的应用主dll名.dll；自包含部署场景下，processPath要指向根目录下的应用exe文件，不能出现路径错配、指向空值的问题。
• 核对项目SDK配置：如果项目文件里的SDK选成了Microsoft.NET.Sdk而非Microsoft.NET.Sdk.Web，哪怕本地用调试配置能正常跑，发布输出也会缺少Web宿主启动逻辑，部署后必然触发全路径404。

排查部署路径的常见错配 #

• 通过Kudu高级工具站点打开Site/wwwroot目录，确认所有发布文件都直接放在wwwroot根目录下，不要出现“wwwroot嵌套一层publish文件夹”的结构。这类问题在FTP上传、拖拽发布场景中出现概率极高，站点找不到根目录下的启动文件，就会对所有请求统一返回404，不管是静态文件还是接口路由。
• 部署新包之前，清空wwwroot下的所有旧文件，不要混合旧版本的web.config、dll文件。如果之前部署过其他版本的应用，残留的旧启动配置会优先被IIS加载，导致新应用无法被正常识别。

定位404的实际触发来源 #

• 暂时关闭Azure App Service的自定义404跳转规则，查看404响应的响应头：如果响应头里没有ASP.NET Core应用的生成标识，说明请求根本没有走到你的应用代码，问题出在宿主层配置；如果响应头带有应用层标识，再回头核对控制器的路由模板和实际请求路径是否匹配，排除“请求了不存在路由”的低级错误。
• 把和Azure上完全一致的发布包，解压到本地IIS站点做复现测试，按照和线上完全相同的路径发起请求，确认本地IIS环境下能不能正常访问，快速拆分问题属于“代码/发布包缺陷”还是“Azure平台配置问题”。

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