在ASP.NET Core应用中，请求从进入管道到返回响应会经过一系列中间件。如果某个控制器或服务抛出未捕获的异常，默认情况下框架会触发开发者异常页或直接返回500错误，前端无法拿到统一的错误结构。通过自定义异常中间件，我们可以在所有业务中间件之外包裹一层捕获逻辑，将异常转换为约定格式再写回响应体。
为什么需要全局异常中间件
传统做法是在每个Action中用try-catch包裹逻辑，但这样会造成大量重复代码，且容易遗漏某些服务层抛出的异常。当项目规模扩大，分散的错误处理让维护成本陡增。全局异常中间件位于管道前端，能够拦截后续所有中间件及终结点执行中未处理的异常，保证错误出口唯一。
另外，不同客户端对错误的消费方式不同。Web API希望收到JSON结构如{code, message}，而传统页面可能希望跳转错误页。中间件可以根据请求首部或接受类型动态决定响应形式，这种集中控制是零散try-catch难以实现的。同时它也能避免将敏感堆栈暴露给外部用户。
中间件执行顺序与注册位置
在Program.cs中，中间件的注册顺序决定了执行顺序。异常中间件应当尽量靠前注册，但又必须在路由和终结点中间件之前，这样才能捕获它们内部的异常。典型顺序为：异常处理中间件 -> 路由 -> 鉴权 -> 终结点。如果放在UseEndpoints之后，终结点里的异常就无法被捕获。
下面的代码展示了基础注册方式。注意UseMiddleware扩展方法将我们自定义的类型加入管道，框架会自动解析构造函数依赖。
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
// 注册全局异常中间件，放在路由之前
app.UseMiddleware<GlobalExceptionMiddleware>();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
app.Run();
实现自定义异常中间件
中间件本质是一个包含InvokeAsync方法的类，构造函数接收RequestDelegate指向下一个中间件。我们在try块中调用next(context)，catch块中处理异常并写回响应。需要注意不能吞掉异常后不返回任何内容，否则客户端会一直等待。
以下示例实现了一个简单的JSON异常响应。我们通过context.Response.Clear()重置可能已写入的状态码，再设置为500并序列化错误模型。对于特定业务异常，可在此之前判断类型以返回更合适的状态码。
using System.Text.Json;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
public class GlobalExceptionMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<GlobalExceptionMiddleware> _logger;
public GlobalExceptionMiddleware(RequestDelegate next, ILogger<GlobalExceptionMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
try
{
await _next(context);
}
catch (Exception ex)
{
_logger.LogError(ex, "未处理的全局异常");
await HandleExceptionAsync(context, ex);
}
}
private static async Task HandleExceptionAsync(HttpContext context, Exception ex)
{
context.Response.ContentType = "application/json";
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
var result = JsonSerializer.Serialize(new
{
code = 500,
message = "服务器内部错误"
});
await context.Response.WriteAsync(result);
}
}
区分环境与自定义异常
开发环境下，我们可能希望看到详细堆栈以便调试；生产环境则应返回模糊提示。可以通过IHostEnvironment判断。同时定义业务异常类，如BusinessException，在捕获时映射为400及具体消息，而不是统一500。
改造HandleExceptionAsync方法，优先处理已知异常类型。这样控制器中只需throw new BusinessException("参数无效")，中间件就会返回对应结构，业务代码保持干净。
public class BusinessException : Exception
{
public int Code { get; }
public BusinessException(string message, int code = 400) : base(message)
{
Code = code;
}
}
private static async Task HandleExceptionAsync(HttpContext context, Exception ex)
{
context.Response.ContentType = "application/json";
if (ex is BusinessException be)
{
context.Response.StatusCode = be.Code;
var body = JsonSerializer.Serialize(new { code = be.Code, message = be.Message });
await context.Response.WriteAsync(body);
return;
}
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
var err = JsonSerializer.Serialize(new { code = 500, message = "服务器内部错误" });
await context.Response.WriteAsync(err);
}
与内置中间件的取舍
ASP.NET Core自带UseExceptionHandler，它可指向错误终结点。但自定义中间件更灵活，能直接控制响应格式且无需额外路由。若项目简单，用内置处理器减少代码量；若需精细控制API错误契约，自写中间件更合适。
无论哪种方式，都应避免在中间件中做重操作，如远程日志上报建议异步 fire-and-forget，防止阻塞响应。同时记得在catch中记录日志，便于线上排查。
| 方案 | 优点 | 缺点 |
|---|---|---|
| 自定义中间件 | 响应格式完全可控，无额外路由 | 需自行编写维护 |
| UseExceptionHandler | 框架内置，配置简单 | 错误页与API格式需额外协调 |
总结实践要点
实现全局异常处理的核心是把捕获点放在管道早期且覆盖终结点。通过区分异常类型与环境，既能保护系统信息，又能给前端稳定接口。将示例代码中的中间件注册到Program后即可生效，后续业务只需抛异常而不必关心怎么回包。
建议把错误模型统一定义在公共类库，前端依此对接。若使用MVC视图，也可在中间件中判断Accept头返回错误视图，实现一套逻辑兼容多端。
C#ASP.NET_Core全局异常处理修改时间：2026-08-08 23:21:28