Azure 部署 Web.config 添加 httpModules 導致 500 錯誤的排查指南

現象

本地 IIS 正常，部署至 Azure Web Apps / 雲服務後報 HTTP 500，疑似 <httpModules> 節點配置不兼容。

核心差異：IIS 管線模式

解決步驟

1. 遷移配置節點：將 <httpModules> 內容移至 <system.webServer><modules>
2. 添加 runAllManagedModulesForAllRequests（如需處理靜態文件）：

   <system.webServer>
     <modules runAllManagedModulesForAllRequests="true">
       <add name="MyModule" type="Namespace.MyModule" />
     </modules>
   </system.webServer>
   

3. 啟用詳細錯誤：在 Azure 門戶「應用服務」→「診斷與解決問題」→「Web 應用程式錯誤」查看具體異常堆棧
4. 檢查預編譯/依賴項：確保模組所在程序集已部署至 bin 目錄

常見誤區

• 保留舊版 <system.web><httpModules> 導致整合管線忽略模組
• 模組類未標記 public 或命名空間拼寫錯誤
• 未在 <modules> 中指定 preCondition="managedHandler" 導致靜態資源也觸發模組（視需求調整）

若為 Azure 雲服務，需在 WebRole.cs 的 OnStart 中配置啟動任務安裝模組，或使用啟動命令註冊。