HTTP Error 502.5 根本原因是运行时缺失或版本不匹配；需安装对应版本的 ASP.NET Core Runtime Hosting Bundle，发布用 --self-contained false，应用池设为 No Managed Code，并确认 web.config 存在且正确。
ASP.NET Core 应用在 IIS 中启动失败，提示“HTTP Error 502.5 - Process Failure”
这基本是部署时最常遇到的错误，根本原因不是 IIS 配置错，而是 dotnet 运行时没装、版本不匹配，或应用没发布为自包含/框架依赖正确形态。
实操建议：
- 检查目标服务器是否安装了对应版本的
ASP.NET Core Runtime Hosting Bundle（不是 SDK！），下载地址在微软官网搜 “Hosting Bundle”，选与项目TargetFramework匹配的版本（如net8.0就装 8.x 的 Bundle） - 确认发布时用了
dotnet publish -c Release -r win-x64 --self-contained false（推荐--self-contained false，依赖系统级运行时，省空间且与 IIS 集成更稳） - 在 IIS 应用程序池中，.NET CLR 版本必须设为
No Managed Code—— ASP.NET Core 不走传统 CLR 管道，设成v4.0或其他会直接报 502.5 - 检查
web.config是否生成成功：发布后根目录下必须有它，且其中<aspnetcore processpath="dotnet" arguments=".\YourApp.dll"> 路径要准确；若用子文件夹部署，<code>arguments中的 DLL 名称和大小写必须完全一致
web.config 手动改过却没生效，或者被发布过程覆盖
web.config 是 IIS 和 ASP.NET Core 的关键粘合层，但它的生成逻辑容易被误解：它不是“写一次就不管”，而是每次 dotnet publish 都会重新生成（除非你显式禁用）。
实操建议：
- 不要直接编辑发布后的
web.config—— 下次发布就没了。应在项目根目录放一个web.config（内容可为空或只含注释），然后在.csproj中加：<PropertyGroup> <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled> </PropertyGroup>
再发布，这样会保留你的手工配置 - 常见需手动干预的项：增加环境变量（如
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />）、调整 stdout 日志路径（stdoutLogEnabled="true"时确保stdoutLogFile指向 IIS 应用池用户有写权限的目录）、设置forwardWindowsAuthToken="false"（避免 Windows 身份验证干扰） - 如果用 CI/CD 自动发布，注意 Git 忽略规则别把
web.config排除掉，否则构建机上不会复制它过去
IIS 上多个 ASP.NET Core 站点共存，端口或路径冲突
ASP.NET Core 默认监听 http://localhost:5000，但 IIS 反向代理时这个地址只是内部通信用，真正冲突点在于：应用程序池标识权限、物理路径访问权、以及 applicationHost.config 中的 handler 注册是否唯一。
实操建议：
- 每个站点必须使用独立的应用程序池（不能共用），且池的“标识”建议用专用域账户或至少是
ApplicationPoolIdentity—— 否则静态文件读取、日志写入可能因权限不足静默失败 - 检查
%windir%\System32\inetsrv\config\applicationHost.config中是否重复注册了aspNetCorehandler，重复会导致启动报错；正常应只有 1 处<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" /> - 若站点启用了 HTTPS 重定向，确认
app.UseHttpsRedirection()和 IIS 的“要求 SSL”设置不叠加 —— 否则可能无限跳转或返回 500 - 调试时可在站点根目录加个
test.html，用浏览器直访 IIS 绑定地址看是否能打开，排除 DNS、防火墙、绑定 Host 头等网络层问题
部署后静态文件（CSS/JS）404，或路由刷新 404
这不是 IIS 配置遗漏，而是 ASP.NET Core 的中间件顺序或默认行为导致的：静态文件中间件没启用，或 SPA 回退路由没配，或 IIS 自身的静态文件处理抢在了 Core 前面。
实操建议：
- 确保
Program.cs中调用了app.UseStaticFiles()，且位置在app.UseRouting()之后、app.UseEndpoints()之前；若用的是MapFallbackToFile("index.html")，要放在所有MapControllerRoute之后 - 检查 IIS 是否启用了“静态内容”功能（Windows 功能 → Internet Information Services → WWW 服务 → 常见 HTTP 功能 → 静态内容），未启用会导致 .js/.css 请求直接 404，不进 ASP.NET Core 管道
- 对于 Vue/React 等 SPA，IIS 的
web.config需补充重写规则（非必须，但比 Core 层回退更早拦截）：<system.webServer> <rewrite> <rules> <rule name="SPA fallback" stopProcessing="true"> <match url=".*" /> <conditions logicalGrouping="MatchAll"> <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> </conditions> <action type="Rewrite" url="/index.html" /> </rule> </rules> </rewrite> </system.webServer>
部署真正卡住的地方，往往不在“怎么配 IIS”，而在于没意识到 dotnet 运行时是独立组件、web.config 是动态生成物、以及 IIS 和 Core 的职责边界在哪里。多看 stdoutLogFile 和 Windows 事件查看器里的“应用程序”日志，比反复重启应用池有用得多。
