Django异常处理技巧：自定义中间件捕获全局错误

本文深入解析了Django在生产环境（DEBUG=False）下隐藏500错误详情的安全设计本质，并系统传授如何通过精心编写的自定义异常处理中间件实现安全、可控、可观测的全局错误捕获——从确保中间件位置靠前、避免二次异常、精准区分API与页面响应，到兼容ASGI异步场景、规避静默失败盲区，手把手教你构建既能记录完整traceback、触发智能告警，又不泄露敏感信息、不影响开发调试体验的健壮错误处理机制。

为什么 Django 的 DEBUG=False 下 500 页面不显示错误详情

因为 Django 默认在生产模式下屏蔽了异常回溯，不是 bug，是安全策略。你看到的空白 500 或 Nginx 的 502，往往只是表象——真实异常其实被吞掉了，或者只记在日志里没配置好。

关键不是“怎么显示错误”，而是“怎么让错误可定位、可响应、不暴露敏感信息”。自定义中间件是可控性最强的方式，比单纯靠 LOGGING 配置更主动。

• DEBUG=True 时中间件捕获的异常仍会进调试页面，不影响开发体验
• 必须把自定义中间件放在 MIDDLEWARE 列表靠前位置（比如在 SecurityMiddleware 之后、CommonMiddleware 之前），否则部分异常（如 URL 解析失败）根本到不了你这里
• 不要在中间件 process_exception 里 raise 新异常，否则可能触发二次 500，尤其在异步视图或流式响应场景下容易卡死

写一个真正能用的 process_exception 中间件

它得做三件事：记录完整 traceback、区分用户可见提示、必要时触发告警。不是所有异常都该返回 JSON，也不是所有都该发邮件。

示例中间件核心逻辑：

class ExceptionLoggingMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
<pre class="brush:python;toolbar:false;">def __call__(self, request):
    return self.get_response(request)

def process_exception(self, request, exception):
    # 只对非调试环境做精细处理
    if not settings.DEBUG:
        logger.error(
            "Uncaught exception on %s %s",
            request.method,
            request.path,
            exc_info=exception,
        )
        # 区分 API 请求和页面请求
        if request.path.startswith('/api/'):
            return JsonResponse({'error': 'Internal server error'}, status=500)
        else:
            return render(request, '500.html', status=500)

• exc_info=exception 是关键，缺了它日志里只有字符串，没有 traceback 对象，无法做 stack inspection
• 用 request.path.startswith('/api/') 比检查 Accept header 更稳——后者容易被 curl 或测试工具乱设
• 不要在中间件里调用 render() 处理模板时依赖未初始化的上下文处理器，500 页面应尽量静态或只用内置变量（如 STATIC_URL）

Django 4.1+ 的 AsyncMiddleware 怎么兼容同步异常处理

如果你项目已启用 ASGI 并用了 async view，但中间件还是同步写的，process_exception 会被跳过——Django 不会把异步异常转给同步中间件。

必须显式声明支持异步，且不能混用 __call__ 和 process_exception 的同步/异步版本：

class AsyncExceptionMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
<pre class="brush:python;toolbar:false;">def __call__(self, request):
    return self.get_response(request)

async def process_exception(self, request, exception):
    if not settings.DEBUG:
        logger.error("Async exception", exc_info=exception)
        # 注意：async render 或 JsonResponse 需要 await
        if request.path.startswith('/api/'):
            return JsonResponse({'error': 'Server error'}, status=500)

• 只要定义了 async process_exception，就必须确保整个中间件生命周期是异步友好的；__call__ 保持同步没问题，但别在里面 await 任何东西
• JsonResponse 本身是同步类，直接 return 没问题；但如果你要读数据库或调外部 API 做错误归因，就得用 sync_to_async 包一层
• ASGI 下 process_exception 可能被多次调用（比如 middleware chain 中多个中间件都实现了它），避免重复发告警，加个 request.META.setdefault('EXCEPTION_HANDLED', False) 做标记

哪些异常根本进不了 process_exception

中间件只捕获视图函数执行中抛出的异常。以下几类不会触发它：

• WSGI/ASGI 层崩溃（如 UnicodeDecodeError 在解析 POST body 时发生）→ 这类需要靠服务器层日志（如 Gunicorn 的 --capture-output）
• URLconf 解析失败（NoReverseMatch 是运行时的，但 urlpatterns 语法错是启动时报）→ 启动阶段异常不在请求生命周期内
• 数据库连接池耗尽、Redis timeout 等底层 I/O 异常 → 如果发生在 middleware 之外（如 signal handler、management command），也不会被捕获
• SystemExit、KeyboardInterrupt 这类信号异常 → Django 显式忽略它们，防止意外终止 worker

真正难缠的是那些“静默失败”：比如缓存后端挂了但没抛异常，只是返回 None；或者 Celery task 内部异常没 propagate 上来。这些得靠业务层埋点，不是中间件能兜底的。

今天关于《Django异常处理技巧：自定义中间件捕获全局错误》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！