HTTP 错误 <httpErrors>

  • 项目

概述

使用 <httpErrors> 元素，你可以为网站或应用程序配置自定义错误消息。 使用自定义错误消息，你可以在网站访问者无法访问所请求的内容时，通过提供文件、返回另一资源或者重定向到某个 URL 来提供友好或者信息更丰富的响应。 例如，你可能想要自定义网站的每个错误消息页面，使其与网站的其他页面外观相同。

<httpErrors> 元素包含一组 <error> 元素，每个元素定义了 IIS 用于响应特定 HTTP 错误的错误消息。 要在 IIS 中添加自定义错误消息，可以将 <error> 元素添加到站点、应用程序或 URL 的 Web.config 文件中的 <httpErrors> 元素中。 每个 <error> 元素都使用 responseMode 属性来指定 IIS 是处理静态内容、动态内容还是重定向到单独的 URL 以响应错误。

如果错误消息集合是你的站点或应用程序从 IIS 配置层次结构中的更高级别继承而来，则可以使用 <remove> 元素从错误消息集合中删除特定的错误消息。 此外，如果 HTTP 错误消息集合是你的站点或应用程序继承继承而来，则可以使用 <clear> 从错误消息集合中移除所有 HTTP 错误消息。

<httpErrors> 元素还包含某些属性，可用于将 IIS 7 配置为处理导致错误的请求。 existingResponse 属性定义当服务器返回 HTTP 错误状态代码时 IIS 7 对现有响应执行的操作。 如果为 <error> 元素中的 responseMode 属性选择指定 File，则 defaultPath 属性定义客户错误页面的路径。

detailedMoreInformationLink 属性指定一个链接，后者可提供有关某个特定错误的详细信息。

<httpErrors> 元素还可以包含 errorMode 属性，可用于控制发生 HTTP 错误时 IIS 返回给浏览器的详细信息级别。 可以将 errorMode 属性设置为 DetailedLocalOnly，这是默认设置，也可以将其设置为 Custom 或 Detailed。 如果指定 DetailedLocalOnly，或者未指定 errorMode 值，IIS 将仅将详细的错误信息返回到本地服务器上的浏览器，向外部计算机上的浏览器返回自定义错误消息。 如果将 errorMode 值设置为 Custom，则 IIS 仅向所有发出请求的浏览器返回自定义错误消息。 如果将 errorMode 值设置为 Detailed，IIS 会将详细的错误信息返回到所有发出请求的浏览器。 默认值 DetailedLocalOnly 可让您排查本地服务器上的 HTTP 错误，同时又不会向外部浏览器公开敏感信息。

默认情况下，IIS 提供的错误消息是在 %SystemRoot%\Help\IisHelp\Common 文件夹中的文件中定义的。 你可以为用户创建自定义错误消息，并将 IIS 配置为在站点上遇到特定 HTTP 错误时返回此页面。

兼容性

版本 说明
IIS 10.0 <httpErrors> 元素在 IIS 10.0 中未进行修改。
IIS 8.5 <httpErrors> 元素在 IIS 8.5 中未进行修改。
IIS 8.0 <httpErrors> 元素在 IIS 8.0 中未进行修改。
IIS 7.5 为 IIS 7.5 中的 <httpErrors> 元素增加了 allowAbsolutePathsWhenDelegated 属性
IIS 7.0 <httpErrors> 元素是在 IIS 7.0 中引入的。
IIS 6.0 <httpErrors> 元素取代了 IIsWebService 元数据库对象的 IIS 6.0 HttpErrors 属性。

安装

<httpErrors> 元素包含在 IIS 7 的默认安装中。

操作方式

如何添加自定义错误页

  1. 打开 Internet Information Services (IIS) 管理器：

    • 如果使用的是 Windows Server 2012 或 Windows Server 2012 R2：

      • 在任务栏上，单击“服务器管理器”，单击“工具”，然后单击“Internet Information Services (IIS)管理器”。

    • 如果使用的是 Windows 8 或 Windows 8.1：

      • 按住 Windows 键，按字母 X，然后单击“控制面板”。
      • 单击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

    • 如果使用的是 Windows Server 2008 或 Windows Server 2008 R2：

      • 在任务栏上，单击“开始”，指向“管理工具”，然后单击“Internet Information Services (IIS)管理器”。

    • 如果使用的是 Windows Vista 或 Windows 7：

      • 在任务栏上，单击“开始”，然后单击“控制面板”。
      • 双击“管理工具”，然后双击“Internet Information Services (IIS) 管理器”。

  2. 在“连接”窗格中，展开服务器名称，展开“站点”，然后导航到要为其配置自定义错误页面的网站或应用程序。

  3. 在“主页”窗格中，双击“错误页面”。
    Screenshot that shows the Error Pages double-clicked.

  4. 在“操作”窗格中，单击“添加...”。

  5. 在“添加自定义错误页”对话框中的“状态代码”下，键入要为其创建自定义错误消息的 HTTP 状态代码的数量。
    Screenshot that shows the Add Custom Error Page.

  6. 在“响应操作”部分中，执行下列操作之一：

    • 选择“将静态文件中的内容插入到错误响应”中，以提供自定义错误的静态内容（例如，.html文件）。
    • 选择“在此站点上执行 URL”以提供自定义错误的动态内容，例如 .asp 文件。
    • 选择“使用 302 重定向进行响应”，以将客户端浏览器重定向到包含自定义错误文件的其他 URL。

  7. 如果选择了“将静态文件中的内容插入到错误响应中”，请在“文件路径”文本框中键入自定义错误页的路径；如果选择了“在此站点上执行 URL”或“使用 302 重定向进行响应”，请键入自定义错误页的 URL，然后单击“确定”。

    注意

    如果选择“在此站点上执行 URL”，则路径必须是相对路径。 如果选择“使用 302 重定向进行响应”，则 URL 必须是绝对 URL。

配置

使用 ApplicationHost.config 文件，可以在服务器级别配置 <httpErrors> 元素，使用相应的 Web.config 文件，则可以在站点和应用程序级别配置。

特性

属性 说明
allowAbsolutePathsWhenDelegated 可选布尔属性。

如果设置为 true，则委托 <httpErrors> 节时，允许自定义错误页使用绝对路径。 设置为 false 时，则仅允许使用相对于站点根目录的路径。

默认值为 false。
defaultPath 可选的字符串属性。

指定自定义错误页的默认路径。 路径的类型由 defaultResponseMode 属性确定。 如果选择 File，则返回文件路径。 如果选择 ExecuteURL 或 Redirect 路径类型，则返回自定义错误页的 URL。
defaultResponseMode 可选枚举特性。

指定如何返回自定义错误内容。

defaultResponseMode 属性可以是下列可能值之一；默认值为 File。
值 说明
File 提供自定义错误的静态内容，例如 .html 文件。 如果 responseMode 设置为 File，则路径值必须是文件路径。

数值为 0。
ExecuteURL 提供自定义错误的动态内容，例如 .asp 文件。 如果 responseMode 设置为 ExecuteURL，则路径值必须是服务器相对 URL。

数值为 1。
Redirect 将客户端浏览器重定向到包含自定义错误文件的其他 URL。 如果 responseMode 设置为 Redirect，则路径值必须是绝对 URL。

数值为 2。
detailedMoreInformationLink 可选的字符串属性。

指定页面底部显示的链接，此链接指向包含有关特定错误的详细信息的页面。 可以使用此属性将最终用户指向一个自定义位置，以便向用户显示错误信息。 状态、子状态、HRESULT 和消息 ID 作为查询字符串的一部分发送。

默认值为 https://go.microsoft.com/fwlink/?LinkID=62293。
errorMode 可选枚举特性。

指定是否启用 HTTP 错误。

errorMode 属性可以是下列值之一；默认值为 DetailedLocalOnly。
值 说明
DetailedLocalOnly 如果请求来自本地计算机，则返回详细的错误信息，如果请求来自外部计算机，则返回自定义错误消息。

数值为 0。
Custom 将模块或服务器生成的错误替换为指定的自定义页面。 此模式可用于向最终用户提供更友好的错误消息。

注意：此设置会关闭详细错误，即使对于本地请求也是如此。

数值为 1。
Detailed 将详细的错误信息发送回客户端。 此模式可用于测试和调试网站和应用程序。

数值为 2。
existingResponse 可选枚举特性。

指定当 HTTP 状态代码表示“错误”（即响应代码 >= 400）时现有响应会发生什么情况。

existingResponse 属性可以是以下值之一；默认值为 Auto。
值 说明
Auto 仅当设置了 SetStatus 标志时，才会使响应保持不变。

数值为 0。
Replace 即使设置了 SetStatus 标志，也会替换现有响应。

数值为 1。
PassThrough 如果存在现有响应，则将响应保留不变。

数值为 2。

子元素

元素 说明
error 可选元素。

将 HTTP 错误添加到 HTTP 错误的集合中。
remove 可选元素。

从 HTTP 错误集合中移除对 HTTP 错误的引用。
clear 可选元素。

从 HTTP 错误集合中移除对 HTTP 错误的所有引用。

配置示例

以下配置示例（如果包含在网站或应用程序的 Web.config 文件中）使用了 errorMode 属性，目的是仅允许在本地计算机上显示详细错误消息。 它还使用 defaultResponseMode 属性为站点或应用程序设置响应模式。 然后，此示例移除 500 状态代码的继承错误消息。 接下来，此示例将 prefixLanguageFilePath 属性设置为 IIS 应搜索新的自定义错误页的目录，并将 path 属性设置为 500.htm，即包含自定义错误消息的文件。

<configuration>
   <system.webServer>
      <httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
         <remove statusCode="500" />
         <error statusCode="500"
            prefixLanguageFilePath="C:\Contoso\Content\errors"
            path="500.htm" />
       </httpErrors>
   </system.webServer>
</configuration>

代码示例

以下示例为所有状态代码 404 错误添加了一个新文件，子状态为 5，IIS 返回“URL 序列被拒绝”错误。 在这些示例中，前缀路径设置为“%SystemDrive%\inetpub\custerr”，文件名指定为“404.5.htm”。

AppCmd.exe

appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost

注意

使用 AppCmd.exe 配置这些设置时，必须确保将 commit 参数设置为 apphost。 这会将配置设置提交到 ApplicationHost.config 文件中的相应位置部分。

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
         ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();

         ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
         errorElement["statusCode"] = 404;
         errorElement["subStatusCode"] = 5;
         errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
         errorElement["path"] = @"404.5.htm";
         httpErrorsCollection.Add(errorElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
      Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection

      Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
      errorElement("statusCode") = 404
      errorElement("subStatusCode") = 5
      errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
      errorElement("path") = "404.5.htm"
      httpErrorsCollection.Add(errorElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;

var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection

Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement

adminManager.CommitChanges()