Web.config system.webServer配置 IIS 7+的XML配置节

system.webserver节点必须与system.web并列置于configuration根下，iis 7+集成模式才生效；runallmanagedmodulesforallrequests=”true”慎用；handlers需严格匹配verb/path/type；rewrite中servervariables需enableproxy=”true”才生效。

system.webServer 节点必须放在 configuration 的根下，不能嵌套在 system.web 里

很多人把 <system.webserver></system.webserver> 写在 <system.web></system.web> 里面，IIS 直接忽略整个节——不报错、不生效、连日志都不记。这是最常被卡住的点。

正确位置是和 <system.web></system.web> 并列，都在 <configuration></configuration> 下一级：

<configuration>   <system.web>     <compilation debug="true" />   </system.web>   <system.webServer>     <modules runAllManagedModulesForAllRequests="true" />   </system.webServer> </configuration>

• <system.webserver></system.webserver> 是 IIS 7+ 原生模块（native modules）和集成管道（Integrated Pipeline）的配置入口，只对 IIS 有效，system.web 里的设置对它没影响
• 如果项目部署在 IIS express 或旧版 IIS（如 6.0），这个节会被完全跳过——它只在 IIS 7.0 及以上、且应用池使用“集成模式”时起作用
• 修改后必须重启应用池或回收工作进程，仅刷新浏览器无效

modules runAllManagedModulesForAllRequests=”true” 不要盲目开启

这个配置会让所有请求（包括 .js、.css、.png）都经过 ASP.NET 管道，看似“统一处理”，实则代价很高：静态文件失去 IIS 原生缓存和内核态发送能力，CPU 和内存占用明显上升。

• 真正需要它的场景只有少数几种：自定义 http 模块要拦截静态资源、依赖 HttpContext.Current 的全局中间件、或 mvc 的路由需匹配非 .aspx 扩展名
• 替代方案更推荐：用 <add name="MyModule" type="..." precondition="managedHandler"></add> 显式指定只对托管请求生效
• IIS 8.5+ 支持 preCondition="integratedMode"，但别混用；若应用池是经典模式，system.webServer 大部分子节直接失效

handlers 配置必须匹配 verb + path + type，缺一不可

写了个自定义 handler，但访问时 404 或 500？大概率是 <add></add> 里漏了 verb 或路径模式不匹配。IIS 不会提示“哪个条件没命中”，只会静默失败。

• 常见错误：path="*.ashx" 写成 path="*.ashx?"（问号不是通配符）、verb="GET,POST" 漏掉空格或大小写不一致（IIS 区分大小写）
• type 必须是完整类名 + 程序集名，例如 "MyApp.Handlers.ImageHandler, MyApp"；若程序集不在 bin 下或 GAC 中，会抛 HttpException: Could not load type
• 优先级由配置顺序决定：靠前的 <add></add> 先匹配；想覆盖默认 handler（如 StaticFile），得用 <remove name="StaticFile"></remove> 先清掉

rewrite 规则中 serverVariables 设置需提前启用 proxy 功能

想在重写规则里改 HTTP_X_FORWARDED_FOR 这类头信息？直接写 <servervariables></servervariables> 没用——IIS 默认禁止修改入站头，除非显式打开 enableProxy="true"。

• 错误现象：规则执行成功，但 Request.ServerVariables["HTTP_X_FORWARDED_FOR"] 仍是空，且 IIS 日志里看不到对应字段
• 必须在 <rewrite></rewrite> 根节点加属性：<rewrite enabled="true" enableproxy="true"></rewrite>；否则 <servervariables></servervariables> 被忽略，也不报错
• enableProxy="true" 有安全影响：它允许重写规则伪造客户端 IP，仅应在可信反向代理（如 nginx、azure Front Door）后启用
• 变量名必须带 HTTP_ 前缀（如 HTTP_X_REAL_IP），不能写成 X-Real-IP

system.webServer 的行为高度依赖 IIS 版本、应用池模式、甚至 windows 补丁级别；同一段配置在本地 IIS Express 正常，到服务器上就失效，往往是因为集成管道没开，或者 applicationHost.config 里锁定了某些节——这时候看 %SystemRoot%System32inetsrvconfigapplicationHost.config 的 <sectiongroup></sectiongroup> 锁定状态，比反复试配置更省时间。