Web.config system.webServer handlers IIS处理程序映射

根本原因是path和verb匹配不精确或被前置handler拦截：path须用精确模式（如*.api）、verb需显式列出，precondition须与应用池托管模式一致，且静态文件handler易被误删导致404。

handlers 节点里加了自定义处理程序但没生效

根本原因通常是 path 和 verb 匹配不精确，或者被更靠前的内置 handler 拦截了。iis 的 handler 匹配是顺序优先、严格匹配，不是“包含匹配”。

• path 必须写成具体路径模式，比如 *.api 或 api/<id></id>（后者需配合 URL 重写），不能写 api/* —— IIS 不认通配符斜杠
• verb 默认只响应 GET,HEAD，POST/PUT/delete 需显式列出，漏掉就会 405 Method Not Allowed
• 如果用的是 System.Web.Handlers.TransferRequestHandler，它会把请求转给 ASP.NET 管道，但前提是 preCondition 匹配，常见错误是设成 integratedMode 却在经典模式下运行
• 检查 web.config 是否放在正确目录：handler 只对当前目录及子目录生效，根站点配置不会自动继承到虚拟目录

system.webServer/handlers 和 system.web/httpHandlers 冲突吗

会，而且冲突方式很隐蔽：两个节分别控制不同管道阶段，但最终可能指向同一段逻辑，导致重复执行或 500 错误。

• <system.web>/<httphandlers></httphandlers></system.web> 只在经典模式（Classic Mode）下起作用；<system.webserver>/<handlers></handlers></system.webserver> 是集成模式（Integrated Mode）的唯一入口
• 如果应用池设为集成模式，httpHandlers 完全被忽略 —— 这时删掉它反而能避免误导自己排查
• 混合使用（比如旧项目迁移）容易出现“本地 IIS express 跑得通，上线后 404”，因为开发机默认集成模式，而某些服务器仍跑经典模式
• 判断当前模式：看应用池“托管管道模式”，不是看 web.config 里有没有某个节点

为什么静态文件（如 .js/.css）突然 404，明明没动 handlers

大概率是误删或覆盖了 IIS 默认的静态文件 handler，尤其是删 StaticFile 或改了 preCondition 值。

• IIS 自带的 StaticFile handler 在 system.webServer/handlers 底层，如果在 web.config 中用了 <remove name="StaticFile"></remove>，又没补上等效配置，所有静态资源就挂了
• preCondition="integratedMode" 是默认值，但如果手动改成 preCondition="classicMode"，静态文件在集成模式下直接失能
• 检查是否启用了 modules runAllManagedModulesForAllRequests="true" —— 它会让所有请求（包括 .png）都走 .NET 管道，若没配好 handler 就 404
• 最简验证法：临时删掉整个 <handlers></handlers> 节，看静态文件是否恢复；恢复后再逐条加回自定义项

handler 中的 type 属性怎么写才不报“找不到类型”

type 不是类名全称，而是“程序集名 + 类型全名”，且必须确保程序集已部署、GAC 或 bin 目录可访问。

• 格式必须是 Namespace.ClassName, AssemblyName，比如 MyApp.Handlers.ApiHandler, MyApp —— 少逗号、少空格、大小写错一个字母都失败
• 如果类在 App_Code 下（Web Forms 项目），type 应写为 App_Code.MyHandler，但注意：App_Code 编译后生成的程序集名是随机的，线上环境极不稳定，不推荐
• type 对应的类必须实现 IHttpHandler（同步）或 IAsyncHttpHandler（异步），且要有无参构造函数；有参数构造函数会导致激活失败
• 错误信息通常是 Could not load type 'xxx' 或 Could not load file or assembly 'xxx' —— 先查 bin 目录有没有对应 DLL，再核对 type 字符串

实际部署时最容易被忽略的，是 handler 的 preCondition 和应用池模式之间的隐式绑定，以及 path 匹配对尾部斜杠、查询字符串的零容忍。这些细节不报错，只静默失效。