Django DEBUG=False 时 500 页面不显示错误详情是出于安全策略而非 bug，需通过自定义中间件（置于 MIDDLEWARE 靠前位置）记录 traceback、区分 API/页面响应并避免二次异常，异步环境需适配 AsyncMiddleware。
为什么 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/')比检查Acceptheader 更稳——后者容易被 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 上来。这些得靠业务层埋点，不是中间件能兜底的。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
