Web.config customErrors配置如何实现IIS错误页面重定向模式设置

在ASP.NET应用程序部署到IIS服务器后，一旦出现未捕获异常或触发HTTP错误状态码，默认行为往往是由IIS返回包含堆栈跟踪、物理路径、模块名称等敏感信息的错误页。这类页面对于普通访问者来说非常不友好，而且可能向外部泄露系统实现细节。要改变这一默认表现，可以在网站根目录的Web.config文件中配置<customErrors>节点。该节点属于<system.web>配置组，通过mode属性决定错误页面的重定向行为，通过defaultRedirect属性指定默认跳转页面，并允许使用<error>子节点按HTTP状态码配置不同的目标页面。合理使用这些配置，可以在隐藏错误信息与保留调试能力之间取得平衡。

customErrors节点基础结构与配置模型

<customErrors>节点位于<system.web>配置组内部，配置模型主要由三个部分组成：mode属性、defaultRedirect属性以及<error>子节点。mode是核心属性，决定自定义错误页面在什么条件下生效；defaultRedirect指定未单独匹配到状态码时的默认跳转地址；<error>子节点则可以配置多组状态码映射，让不同错误类型跳转到不同页面。

最基础的配置只需要指定mode和defaultRedirect，示例如下：

<configuration>
  <system.web>
    <customErrors mode="On" defaultRedirect="/error.html">
    </customErrors>
  </system.web>
</configuration>

上述配置中，mode="On"表示对所有访问请求都启用错误重定向，defaultRedirect指向根目录下的error.html页面。由于没有配置具体的错误码映射，因此任何未处理错误都会统一跳转到这个默认页面。如果希望进一步细化不同HTTP状态码的表现，可以继续在<customErrors>节点内部添加<error>子节点。跳转地址既可以使用相对路径，也可以使用绝对路径，实际使用中通常建议优先选择相对路径，以降低站点迁移后的维护成本。

三种重定向模式的详细行为

mode="On"：开启重定向模式

mode="On"表示无论请求来自本地服务器还是远程客户端，只要ASP.NET应用程序发生服务器错误，都会隐藏错误详情，并把用户带到defaultRedirect指定的页面。这种模式适合生产环境，因为它能够阻止敏感信息通过错误页向外泄露。

如果希望针对不同错误类型展示不同页面，可以加入<error>子节点，例如：

<configuration>
  <system.web>
    <customErrors mode="On" defaultRedirect="/500.html">
      <error statusCode="404" redirect="/404.html" />
      <error statusCode="403" redirect="/403.html" />
    </customErrors>
  </system.web>
</configuration>

在这个示例中，默认错误跳转到500.html，而404状态码会单独跳转到404.html，403状态码则跳转到403.html。这样做能够让用户更清楚地知道是页面未找到还是权限不足，避免所有错误都指向同一页面带来的困惑。

mode="Off"：关闭重定向模式

mode="Off"会完全关闭自定义错误页面重定向。此时所有访问者，包括远程用户，都会看到详细的错误堆栈信息，包括异常类型、调用堆栈、源代码行号等。这种模式仅适合开发调试阶段使用，帮助开发者快速定位问题，绝不能应用于对外开放的生产环境。

关闭重定向的配置非常简单：

<configuration>
  <system.web>
    <customErrors mode="Off" />
  </system.web>
</configuration>

在该模式下，即使配置了defaultRedirect或<error>子节点，这些设置也不会生效。浏览器中会直接显示ASP.NET或IIS生成的详细错误页。虽然开发人员可以借此快速发现问题，但攻击者同样能够获取这些实现细节，因此必须严格限制使用范围。

mode="RemoteOnly"：仅远程重定向模式

mode="RemoteOnly"表示仅对远程访问请求执行错误页面重定向，而来自服务器本机的请求仍然显示详细错误信息。这样本机调试时可以继续查看完整堆栈，远程用户则只能看到友好的自定义错误页。它适合测试环境，或者已经上线但需要临时排查问题的场景。

其基本配置如下：

<configuration>
  <system.web>
    <customErrors mode="RemoteOnly" defaultRedirect="/error.html" />
  </system.web>
</configuration>

本地请求通常指通过服务器自身的回环地址或localhost发起的访问，远程请求则指外部网络访问。这一模式兼顾了安全和调试效率，但在内网环境中使用时要特别注意，因为内网中的其他机器访问通常会按远程请求处理，同样会被重定向到错误页面。

自定义错误页面配置的注意事项

在配置redirect地址时，建议优先使用相对路径，例如/error.html或~/error.html。这样即使站点被迁移到其他虚拟目录或域名下，跳转地址也不会失效。使用绝对路径虽然直观，但一旦部署结构发生变化，就需要逐项修改，维护成本较高。

自定义错误页面本身必须足够简单、稳定，不能存在运行时错误。如果错误页面自身抛出异常或触发新的HTTP错误，浏览器可能会在错误页与重定向目标之间反复跳转，最终导致页面无法正常显示。因此错误页面最好使用静态HTML文件，或经过充分测试的轻量级ASP.NET页面。

此外还需要注意以下几个问题：

• <error>子节点仅支持标准HTTP状态码，例如404、403、500等，自定义状态码无法被识别并生效。
• IIS层面如果也配置了错误页，它的处理优先级通常高于ASP.NET层面的customErrors配置，因此如果两者同时存在，需要确保IIS错误页设置不会覆盖或干扰自定义错误页的正常跳转。尤其是在共享主机或由运维统一管理IIS的环境中，开发人员可能无法直接修改IIS配置，此时更应依赖customErrors来保证应用自身具备完整的错误处理能力。 错误页面跳转的常见问题中，还有一个容易被忽视的细节：302重定向与状态码保留。customErrors的defaultRedirect和error子节点通常通过302临时重定向将用户引导到指定错误页。对于SEO和用户体验而言，这并不理想。搜索引擎蜘蛛遇到404状态码时，如果最终被302跳转到200状态的错误页，可能会将错误页视为正常内容索引，造成重复内容或误导性收录。对于API接口来说，客户端期望获得明确的404或500状态码，而302重定向会破坏RESTful语义，使客户端无法正确判断请求结果。因此在对状态码要求严格的场景下，与其使用重定向，不如直接返回带有正确状态码的错误视图。在ASP.NET MVC或Web API中可以配合HandleErrorAttribute或自定义异常过滤器实现这一点，而Web Forms则可以通过在错误页面的代码逻辑中使用Response.StatusCode来显式设置状态码，即使使用了redirect也可以通过Server.Transfer代替Response.Redirect来保留原始状态码。 Server.Transfer与Response.Redirect在执行机制上有本质区别。Response.Redirect会向浏览器发送一个302响应，浏览器收到后发起第二次请求，地址栏会改变，原始状态码丢失。Server.Transfer则在服务器内部将请求转交给另一个页面处理，浏览器无感知，地址栏保持不变，原始HTTP状态码可以被保留。因此如果必须在customErrors中配置跳转，又希望保留原始状态码，可以考虑在Global.asax的Application_Error事件中使用Server.Transfer来处理未捕获的异常，而不是完全依赖customErrors的自动重定向。一个典型的Application_Error处理逻辑如下：

  protected void Application_Error(object sender, EventArgs e)
  {
      var exception = Server.GetLastError();
      var httpException = exception as HttpException;
      
      if (httpException != null)
      {
          int statusCode = httpException.GetHttpCode();
          Response.StatusCode = statusCode;
          
          if (statusCode == 404)
          {
              Server.Transfer("/errors/notfound.html");
          }
          else
          {
              Server.Transfer("/errors/general.html");
          }
      }
      else
      {
          Response.StatusCode = 500;
          Server.Transfer("/errors/general.html");
      }
      
      Server.ClearError();
  }
  

  这段代码首先通过Server.GetLastError获取最后一个未处理异常，然后判断它是否为HttpException类型。如果是，则调用GetHttpCode方法获取具体的HTTP状态码，并据此决定跳转到哪个错误页。404跳转到专门的“页面不存在”页面，其余状态码则跳转到通用错误页。对于非HttpException类型的异常，统一视为500内部错误处理。最后调用Server.ClearError清除异常状态，避免异常继续向上传播。这种方式的优势在于服务器内部转发不产生额外的网络往返，用户看到的地址栏仍然是原始请求地址，同时响应状态码也能准确反映错误类型。但Server.Transfer本身也有一些限制，它只能在同一应用程序内部转交，不能跨虚拟目录或跨站点。此外如果错误发生在异步请求或某些特殊管道事件中，Server.Transfer可能无法正常工作，因此它仍然是customErrors以外的一种补充手段，而不是完全替代方案。 对于大型应用来说，错误处理还需要考虑日志记录和监控。无论使用customErrors还是Application_Error，捕获到异常后都应该记录详细信息，包括异常堆栈、请求URL、用户身份、时间戳、HTTP方法、请求头等关键上下文。这些信息对事后排查问题至关重要。日志记录通常使用成熟的日志框架，例如log4net、NLog或.NET内置的TraceSource。日志可以写入文本文件、数据库、Windows事件日志或集中式日志平台。需要注意不要在日志中记录敏感信息，例如密码、令牌、身份证号等，以免造成二次泄露。在应用层记录异常的同时，IIS的访问日志和Windows事件日志也可以作为辅助排查手段。 考虑到高可用和负载均衡环境，错误日志的集中化管理变得更加重要。当请求可能被分发到不同服务器时，单机日志文件难以追踪一次完整的请求链路。此时可以将日志写入统一的日志收集系统，或至少保证每台服务器的时钟同步，以便根据时间戳在不同日志文件之间对齐。对于严重的应用错误，还可以结合监控告警机制，在错误率超过阈值时自动通知运维人员，缩短故障发现时间。 自定义错误页面的用户体验设计也值得投入精力。一个友好的错误页应当清晰地告诉用户发生了什么，并提供可执行的后续操作。例如在404页面中提供搜索框、热门文章链接或返回首页的按钮。在500页面中则应当向用户致歉，并说明技术团队已经收到错误通知，同时提供稍后重试或联系客服的途径。错误页面的视觉风格应与站点整体保持一致，避免用户误以为离开了原站点。不过无论错误页面设计得多好，它都不应该暴露任何内部技术细节，例如堆栈跟踪、数据库连接字符串、服务器路径、框架版本等。这些信息一旦被攻击者获取，就可能被用来寻找进一步的突破口。 在现代ASP.NET Core中，错误处理机制与传统的Web Forms有较大差异。customErrors节点在ASP.NET Core中不再适用，取而代之的是中间件管道中的异常处理组件。最常用的是UseExceptionHandler和UseStatusCodePages。UseExceptionHandler可以在管道中捕获未处理异常，并重定向到指定的错误处理终结点。它的配置如下：

  var app = builder.Build();
  
  if (!app.Environment.IsDevelopment())
  {
      app.UseExceptionHandler("/Home/Error");
  }
  else
  {
      app.UseDeveloperExceptionPage();
  }
  
  app.UseStatusCodePagesWithReExecute("/Home/StatusCode", "?code={0}");
  
  app.UseRouting();
  app.MapControllerRoute(
      name: "default",
      pattern: "{controller=Home}/{action=Index}/{id?}");
  
  app.Run();
  

  在这个例子中，非开发环境使用UseExceptionHandler将所有未处理异常路由到/Home/Error终结点，由该终结点负责展示友好错误页并记录日志。开发环境则保留开发者异常页，以便查看详细的堆栈信息。UseStatusCodePagesWithReExecute是针对状态码错误（如404、403）的处理方案，它会在服务器内部重新执行指定路径，并将原始状态码作为查询字符串参数传递。这里使用了模板“?code={0}”，其中{0}会被实际状态码替换。这样错误处理终结点既可以知道用户原本遇到了什么错误，又不必依赖外部重定向。与传统的customErrors相比，中间件方案更灵活，也更符合ASP.NET Core的管道模型。 对于ASP.NET Core中的API项目，错误处理又有不同的侧重。当API返回404或500时，客户端期望的是机器可读的JSON或XML响应，而不是HTML错误页面。因此UseStatusCodePages的HTML重定向方案通常不适用于纯API场景。API的错误处理更倾向于使用异常过滤器或自定义中间件，统一捕获异常后返回结构化的错误响应。例如：

  app.Use(async (context, next) =>
  {
      try
      {
          await next();
      }
      catch (Exception ex)
      {
          context.Response.StatusCode = 500;
          context.Response.ContentType = "application/json";
          await context.Response.WriteAsync(
              System.Text.Json.JsonSerializer.Serialize(new 
              { 
                  error = "Internal Server Error",
                  traceId = context.TraceIdentifier
              })
          );
      }
  });
  

  这段中间件代码包裹了后续管道，当后续中间件或控制器抛出未处理异常时，catch块会捕获它，将响应状态码设置为500，内容类型设置为JSON，并返回一个包含错误信息和跟踪ID的JSON对象。TraceIdentifier是ASP.NET Core为每个请求生成的唯一标识符，返回给客户端后可以方便地在日志中定位具体请求。这种结构的错误响应对于前端开发者和API集成方来说十分友好。 回到传统ASP.NET Web Forms的场景，在实际部署中还需注意customErrors与不同IIS版本的交互。IIS 7及以上版本引入了自己的错误页配置系统，存储在web.config的system.webServer节点下的httpErrors元素中。httpErrors的配置独立于customErrors，它作用于IIS管道级别，可以捕获来自ASP.NET和静态文件处理的所有错误。如果httpErrors配置为自定义错误页，而customErrors又配置了defaultRedirect，那么在同一错误场景下可能产生冲突。典型的表现是用户访问不存在的静态文件时，IIS错误页生效；而访问不存在的ASP.NET页面时，customErrors生效。这种不一致的行为会导致错误处理表现分裂，因此最佳实践是在项目中统一两套配置，保证行为一致。如果必须二选一，推荐在IIS 7及以上环境统一使用httpErrors，因为它覆盖范围更广，且支持更细粒度的状态码和子状态码配置。 httpErrors的配置示例如下：

  <system.webServer>
    <httpErrors errorMode="Custom" existingResponse="Replace">
      <remove statusCode="404" subStatusCode="-1" />
      <error statusCode="404" path="/errors/notfound.html" responseMode="ExecuteURL" />
      <remove statusCode="500" subStatusCode="-1" />
      <error statusCode="500" path="/errors/general.html" responseMode="ExecuteURL" />
    </httpErrors>
  </system.webServer>
  

  这里的errorMode设置为Custom表示启用自定义错误页。existingResponse设置为Replace意味着无论ASP.NET层是否已经生成了响应，IIS都会用自定义错误页替换它，这可以有效避免双重响应的混乱。responseMode设置为ExecuteURL表示在服务器内部执行错误页路径，而不是重定向，这样可以保留原始状态码。remove节点用于清除IIS默认的错误页配置，避免继承默认行为。这种配置方式比customErrors更加统一和强大，尤其适合IIS 7及以上版本的部署环境。 在安全加固层面上，错误页面的路径也应当被妥善保护。错误页本身通常放在公开目录下，但如果错误页需要访问数据库或内部服务，则应当将其置于需要认证才能访问的路径之外，或者确保错误页中的敏感操作有独立的权限控制。此外错误页不应该接收来自查询字符串或表单的未验证数据，否则可能被用于反射型XSS攻击。攻击者可能构造一个恶意链接，将脚本注入到错误页的回显内容中。因此在错误页中处理用户输入时，必须进行HTML编码，防止将未转义的内容直接输出到页面。 还需要考虑的一个问题是爬虫和自动化工具对错误页的访问。如果站点有大量404页面被外部链接引用，错误页的访问量可能相当可观。如果错误页每次访问都执行复杂的数据库查询或日志写入，可能对服务器性能造成压力。因此错误页应尽量保持轻量级，避免在错误处理路径中引入不必要的开销。日志写入可以异步进行，避免阻塞错误页的返回。对于高并发环境，甚至可以考虑将错误页托管在CDN或反向代理层，由前端服务器直接返回静态错误响应，减少对后端应用服务器的压力。 综合来看，customErrors是ASP.NET Web Forms时代用于配置友好错误页面的重要手段，它通过mode属性和error子节点提供了灵活的开关和状态码映射能力。On模式可以实现对终端用户的完全屏蔽，Off模式便于开发调试，RemoteOnly模式则在两者之间取得平衡。理解了它的工作原理之后，开发者还需要注意重定向带来的状态码丢失问题，可以结合Server.Transfer、Application_Error等手段进行补充。在IIS 7及以上环境中，httpErrors提供了更底层的统一错误页配置能力，与customErrors之间的优先级和协作关系必须在部署时明确。进入ASP.NET Core时代后，错误处理迁移到了中间件管道中，UseExceptionHandler和UseStatusCodePages成为新的标准工具，API项目则更倾向于返回结构化JSON错误响应。无论使用哪种技术栈，自定义错误页的最终目标是一致的：在保护内部细节不被泄露的前提下，为用户提供清晰、友好的错误提示，同时为开发和运维团队保留足够的诊断信息。只有将安全、性能、可维护性和用户体验综合考虑，才能设计出一套健壮且实用的Web应用错误处理体系。

customErrorsIIS错误页面Web.config配置重定向模式修改时间：2026-07-15 01:21:30