ASP.NET Core 异常中间件：配置、自定义与最佳实践

理解默认异常行为

创建一个标准的 ASP.NET Core 应用程序后，如果直接在控制器或中间件中抛出未捕获的异常，系统会默认拦截并返回简单的 HTTP 500 响应。这种机制保护了生产环境的安全性，但在开发阶段给调试带来了困难。

运行此类应用时，浏览器或其他客户端仅能看到一个通用的错误页面或空响应，如下图所示：

作为开发者，我们需要更详细的信息来确定异常发生的具体位置、异常类型以及相关的环境数据，因此需要引入开发人员异常页面中间件。

启用开发人员异常页面

若希望应用在处理管道中遇到未处理异常时，自动渲染包含丰富调试信息的 HTML 页面，需在 Startup 类的 Configure 方法中注册 UseDeveloperExceptionPage 中间件。

操作入口为项目的启动配置类 Startup.cs（或在 .NET Core 3.0+ 的无 Startup 项目中直接修改 Program.cs）。请在管道初始化阶段添加以下代码：

app.UseDeveloperExceptionPage();

重新运行应用程序并触发异常，此时界面将变为“开发人员异常”页，展示如下详细信息：

该页面通常包含五个核心选项卡，帮助全方位定位问题：

• Stack (堆栈)：提供完整的调用堆栈跟踪，精确指出异常发生的文件名及具体行号。
• Query (查询)：解析 URL 中的查询字符串参数，查看传值情况。
• Cookies：列出随请求发送的所有 Cookie 键值对。
• Headers (标头)：显示客户端发送的 HTTP 请求头信息，便于检查认证令牌或内容类型等。
• Routes (路由)：展示匹配当前请求的路由模式及 HTTP 动词。

注意：如果在 Query 或 Cookies 标签页中看到空白，通常是因为当前请求并未携带对应的数据，这是正常现象。

第1步：自定义中间件选项参数

为了获得更具针对性的调试体验，可以通过 DeveloperExceptionPageOptions 对象对中间件行为进行微调。在 ASP.NET Core 中，多数具有可配置性的中间件都支持 Options 模式。

例如，若要控制异常详情页中源代码片段的展示行数，可以设置 SourceCodeLineCount 属性。该属性定义了错误行之前和之后显示的行数。

修改 Startup.Configure 方法的代码如下：

app.UseDeveloperExceptionPage(new DeveloperExceptionPageOptions
{
    SourceCodeLineCount = 5 // 前后各显示5行源码
});

执行上述配置后，再次触发异常，详情页中的代码块将只展示指定行数的上下文。这有助于在日志或截图中减少冗余信息，聚焦关键区域。观察错误行及其前后的代码行号，即可验证配置生效。

中间件的配置顺序至关重要

中间件的执行顺序遵循“洋葱模型”，即先注册的中间件先执行，但其后置逻辑（On Next）在后注册中间件之后执行。对于异常中间件而言，它必须足够靠前，以便包裹住后续所有可能抛出异常的组件。

第2步：验证错误的配置位置

如果将 UseDeveloperExceptionPage 放在了引发异常的中间件之后，它将无法捕获异常。因为当异常发生时，它已经被后面的中间件抛出并终止了当前请求链，没有机会回传到前面的异常处理器。

假设我们有一个自定义中间件负责抛出自定义异常。若按以下顺序配置：

app.UseCustomMiddleware(); // 自定义中间件，可能抛异常
app.UseDeveloperExceptionPage(); // 放在后面

运行结果将是默认的 HTTP 500 错误，而非详细的调试页面。这说明异常从未到达 UseDeveloperExceptionPage。

第3步：确立正确的管道拓扑

正确的做法是将 UseDeveloperExceptionPage 放置在管道的最前端（在 UseRouting、UseEndpoints 或 UseMvc 之前），确保它能接管整个管道内的未处理异常。标准的最小化项目结构推荐顺序如下：

1. 初始化 IWebHostEnvironment。
2. 根据环境加载 Startup。
3. 创建 IApplicationBuilder。
4. 调用 app.UseDeveloperExceptionPage()。
5. 配置路由和其他业务中间件。

安全警告与总结

重要提醒：UseDeveloperExceptionPage 应仅在 Development 环境下启用。在生产环境中暴露堆栈跟踪、本地文件路径和数据库连接细节极具安全风险。建议在启动配置中结合环境判断：

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Home/Error"); // 生产环境重定向到通用错误页
}