使用Gunicorn部署Flask应用时出现werkzeug.exceptions.ClientDisconnected异常如何解决

• 该异常本质是客户端在请求体还未完全发送到服务器端时就主动断开连接，与是否使用Gunicorn无直接关联：从堆栈信息可看出，异常触发于访问request.files的逻辑执行阶段，此时Werkzeug正在解析客户端上传的multipart表单数据，读取输入流时检测到连接已被客户端关闭，因此抛出ClientDisconnected异常。
• 此前查阅到的Flask官方issue中提到的Werkzeug自带服务器不会排空输入流的问题，为开发服务器独有的缺陷。即便使用Gunicorn这类生产级WSGI服务器，只要出现客户端中途断连的网络场景，Werkzeug仍会抛出该异常，属于正常的网络场景触发错误，并非服务端代码BUG。
• 常见触发场景包括：用户上传大文件时中途关闭页面/断网、前端请求超时设置短于Gunicorn配置的600s导致请求提前终止、反向代理（如Nginx）的上传超时配置过短主动断开连接。

1. 捕获异常避免错误日志刷屏 #

该异常属于正常网络异常，无需特殊业务处理时直接捕获即可：

from werkzeug.exceptions import ClientDisconnected
from flask import request, Flask

app = Flask(__name__)

@app.route('/upload', methods=['POST'])
def upload_handler():
    try:
        # 所有访问request.files、request.form的业务逻辑放在此处
        files = request.files
        # 后续业务处理逻辑
    except ClientDisconnected:
        # 客户端已断开，无需返回响应（也无法正常发送），直接返回空即可
        return ''

如需全局捕获可使用Flask错误处理器：

@app.errorhandler(ClientDisconnected)
def handle_client_disconnect(e):
    # 可记录低级别日志，无需输出错误堆栈
    return '', 499 # 499为行业通用的客户端主动断开请求的状态码

2. 调整各层超时配置降低触发频率 #

如果异常出现频率过高，可依次检查各组件的超时配置：

• 调整前端上传请求的超时时间，不短于后端文件处理所需的最大耗时
• 若服务前部署有反向代理（如Nginx），调整client_max_body_size、client_body_timeout等参数，与Gunicorn配置的600s超时匹配
• 大文件上传场景建议改为分片上传方案，降低单次请求的持续时间，减少中途断连概率

3. 升级依赖版本 #

低版本Werkzeug对部分异常场景的判断存在缺陷，可将Werkzeug和Flask升级到最新稳定版，减少不必要的异常抛出。

内容的提问来源于stack exchange，提问作者abhi