在IIS托管的ASP.NET Core中配置<httpErrors>实现自定义错误响应

1. 配置Web.config #

需要同时配置customErrors和httpErrors，分场景处理不同错误：

1.1 应用正常运行时的错误处理 #

修改system.web和system.webServer节点：

<system.web>
  <customErrors mode="RemoteOnly" redirectMode="ResponseRewrite">
    <error statusCode="404" redirect="/Error/404" />
    <error statusCode="500" redirect="/Error/500" />
  </customErrors>
</system.web>
<system.webServer>
  <httpErrors errorMode="Custom" existingResponse="Auto">
    <remove statusCode="404" subStatusCode="-1" />
    <remove statusCode="500" subStatusCode="-1" />
    <error statusCode="404" path="/Error/404" responseMode="ExecuteURL" />
    <error statusCode="500" path="/Error/500" responseMode="ExecuteURL" />
  </httpErrors>
  <aspNetCore processPath="dotnet" arguments=".\YourApp.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="InProcess" />
</system.webServer>

• existingResponse="Auto"：让IIS根据响应内容自主判断是否替换，配合后续中间件实现精准控制。
• responseMode="ExecuteURL"：直接返回错误页内容，避免重定向，保留原状态码。

1.2 应用无法启动时的错误处理 #

当ASP.NET Core应用无法启动时，Core中间件失效，需单独配置静态错误页：

<httpErrors errorMode="Custom" existingResponse="Auto">
  <!-- 保留其他错误配置 -->
  <error statusCode="500" path="/StaticErrors/500.html" responseMode="File" />
</httpErrors>

提前在站点根目录创建StaticErrors文件夹，放入静态的500.html页面。

2. 添加ASP.NET Core中间件控制响应透传 #

在Program.cs的请求管道中添加中间件，区分API与页面请求，控制IIS是否干预响应：

var app = builder.Build();

// 放置在路由、授权等中间件之前
app.Use(async (context, next) =>
{
    await next();

    if (context.Response.StatusCode >= 400)
    {
        // 根据实际业务调整API请求判断逻辑，比如路径前缀、请求头
        bool isApiRequest = context.Request.Path.StartsWithSegments("/api") 
                          || context.Request.Headers.Accept.Any(h => h.Contains("application/json"));

        if (isApiRequest)
        {
            // 通知IIS跳过自定义错误，透传API的JSON响应
            context.Features.Get<IISHttpFeature>()?.TrySkipIisCustomErrors = true;
            context.Response.Headers["X-Responded-JSON"] = "true";
        }
        // 非API请求，交由IIS返回自定义错误页
    }
});

// 后续中间件配置
app.UseRouting();
app.UseAuthorization();
app.MapControllers();

app.Run();

• TrySkipIisCustomErrors：进程内托管模式下依然有效，并非仅适用于ASP.NET MVC，通过IISHttpFeature即可设置。

3. 场景验证 #

• 访问无效URL（如/non-existent-page）：返回自定义404页。
• API请求不存在资源（如/api/users/9999）：透传API返回的JSON格式404响应。
• API参数错误（如/api/users?invalidParam）：透传API返回的JSON格式400响应。
• IIS无法启动应用：直接返回静态500.html页面。

内容的提问来源于stack exchange，提问作者Oleg Bevz