如何使用Flask的_errorhandler装饰器统一处理异常并返回JSON响应？

本文共计1009个文字，预计阅读时间需要5分钟。

由于 Flask 默认只将未被视图函数处理的异常（非 HTTP 异常子类）交给 `@app.errorhandler(Exception)` 处理，因此很多常见的崩溃（如视图里抛出的 `ValueError`、`TypeError` 等）会被 Flask 自动包装成 `InternalServerError`。这属于 `HTTPException` 子类，但走的是 `@app.errorhandler(500)` 分支，而非 `Exception`。

• 真正能被 @app.errorhandler(Exception) 捕获的，是那些绕过 Flask HTTP 异常体系的“原始异常”，比如在 before_request 中直接 raise KeyError
• 想统一兜底所有服务端错误，必须同时注册 @app.errorhandler(500) 和 @app.errorhandler(Exception)，否则 500 页面或空响应很常见
• 别依赖 Exception 单一装饰器——它不覆盖 HTTPException 及其子类（包括 BadRequest、NotFound 等），这些走的是状态码 handler

怎么让所有错误都返回 JSON，包括 4xx/5xx 和未处理异常？

靠一个 handler 不够，得按错误类型分层拦截：先用 @app.errorhandler(400) 到 @app.errorhandler(500) 覆盖标准 HTTP 状态码，再用 @app.errorhandler(Exception) 收尾非 HTTP 异常。所有 handler 都返回 jsonify() 响应，并显式设 status。

• 每个 handler 函数必须返回一个 Response 对象（如 jsonify() 的返回值），不能只写 return {"error": "xxx"} —— 这会触发默认 HTML 响应
• 注意 HTTPException 实例有 .code 和 .description 属性，可直接用：return jsonify(error=str(e), code=e.code), e.code
• 对 Exception 类型，建议记录日志（app.logger.exception("Uncaught exception")），再返回通用 500 JSON，避免泄露堆栈

@app.errorhandler(404) def not_found(e): return jsonify(error="Resource not found"), 404 @app.errorhandler(500) def internal_error(e): return jsonify(error="Internal server error"), 500 @app.errorhandler(Exception) def unhandled_exception(e): app.logger.exception("Unhandled Exception") return jsonify(error="Something went wrong"), 500

为什么开发时能看到详细错误页，上线后却变空白或 HTML？

因为 app.debug = True 时，Flask 会禁用所有自定义 errorhandler，直接渲染调试页面；上线必须关掉 debug，否则你的 JSON handler 完全不生效。

• app.config["DEBUG"] = False 和 app.run(debug=False) 都要确认，光改 config 不够，run 参数优先级更高
• 用 gunicorn/uwsgi 部署时，确保没在启动命令里加 --reload 或 debug=True 参数
• 检查是否启用了 PROPAGATE_EXCEPTIONS = True —— 它会让异常冒泡出 Flask，跳过 handler，务必设为 False（默认就是 False，但显式设更稳妥）

JSON 错误响应里要不要带 traceback？

绝对不要在生产环境返回 traceback。它暴露代码路径、依赖版本、变量名，是典型安全风险。开发阶段可用 app.config["TRAP_HTTP_EXCEPTIONS"] = True 配合调试器看详情，但上线前必须关掉。

• 如果真需要排查，把完整异常写进日志（用 app.logger.error(..., exc_info=True)），而不是塞进响应体
• 客户端只需要知道 “发生了什么” 和 “该怎么做”，比如 {"error": "invalid_token", "message": "Token expired or malformed"}，不是 Python 的 KeyError: 'user_id'
• 别为了“方便前端”返回 __cause__ 或 __traceback__ 属性——这些字段名本身就在泄漏运行时细节

最麻烦的其实是中间件或扩展（比如 Flask-SQLAlchemy、Flask-JWT-Extended）抛出的异常，它们未必走标准 handler 流程。遇到漏捕获的情况，先查对应扩展文档看是否提供了自己的 error handler 钩子，而不是硬塞进全局 Exception。