如何在IIS服务器部署.Net 6.0 Web API 排查服务器部署异常问题

常见故障原因（安装Hosting包后仍无法启动场景） #

• 安装dotnet-hosting捆绑包后未重启IIS核心服务，AspNetCoreModule模块未加载到IIS中
• IIS应用池配置错误：.NET 5/6属于独立Core运行时，应用池误选了.NET Framework 4.x等CLR版本，未设置为无托管代码模式
• 版本不匹配：本地编译使用的.NET 6 SDK版本和服务器安装的6.0.6运行时存在小版本兼容问题，或Hosting包安装不全缺少ASP.NET Core运行时组件
• 发布文件缺失：迁移到.NET 6后发布配置未更新，导致web.config、模块配置等关键文件缺失
• 权限不足：IIS应用池标识对部署目录没有读取、执行权限，无法加载应用程序集

标准部署操作步骤 #

1. 服务器端运行环境配置 #

• 先卸载服务器上已安装的损坏/版本不匹配的.NET 6运行时、Hosting组件，重启服务器
• 安装和本地编译SDK版本完全一致的.NET 6 Hosting捆绑包（即dotnet-hosting-6.0.x-win.exe，该包会自动安装.NET Runtime、ASP.NET Core Runtime、IIS所需的AspNetCoreModuleV2模块），如果选择独立部署模式可以跳过此步，但发布包体积会大很多
• 安装完成后打开管理员权限的命令行，执行以下命令强制重启IIS相关服务，确保模块加载生效：

  net stop was /y
  net start w3svc
  

• 校验安装结果：打开IIS管理器，点击服务器根节点→功能视图中的「模块」，确认列表中存在AspNetCoreModuleV2项，即说明Hosting组件安装生效。

2. 本地项目发布配置 #

• 右键项目选择「发布」，目标选择文件夹，部署模式选择「框架依赖」，目标运行时选择win-x64（对应64位Windows Server系统）
• 检查项目的.csproj文件，确认目标框架配置为<TargetFramework>net6.0</TargetFramework>，清理掉旧的.NET 5相关的包引用
• 发布完成后检查输出目录，确认根目录存在web.config文件，文件中<aspNetCore>节点的processPath属性值为dotnet，arguments属性指向项目生成的入口DLL。

3. IIS站点配置 #

• 新建IIS站点，物理路径指向发布后的文件目录，绑定对应的端口、域名
• 找到该站点关联的应用程序池，右键打开「基本设置」，.NET CLR版本选择「无托管代码」，托管管道模式选择「集成」
• 给部署目录配置权限：右键文件夹→属性→安全，添加对应用户（格式为IIS AppPool\你的应用池名称），授予「读取和执行」「列出文件夹内容」「读取」三个权限。

4. 启动校验 #

• 先在服务器本地打开命令行，进入部署目录，执行dotnet 你的项目入口.dll，确认命令行启动无报错，能正常监听端口，排除应用本身的启动错误
• 再通过绑定的地址访问站点验证可用性。

快速排查定位方法 #

• 如果页面返回500系列错误，先开启stdout日志：修改部署目录下的web.config，将stdoutLogEnabled="false"改为stdoutLogEnabled="true"，在同目录下新建logs文件夹并给应用池标识授予写入权限，重启站点后访问，查看logs下生成的日志即可定位具体错误（常见为配置项缺失、程序集版本不匹配、数据库连接失败等）
• 如果返回502.5进程启动失败错误，优先执行上文提到的本地命令行启动命令，控制台会直接打印启动失败的具体原因，90%以上的该类错误可以通过这个方式直接定位
• 如果提示AspNetCoreModule模块不存在，重新运行Hosting捆绑包安装程序选择「修复」，完成后再次执行重启WAS、W3SVC的命令即可。

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