Flask-SocketIO搭配Vue部署Nginx时降级为轮询不使用WebSocket问题咨询

• 客户端连接地址配置错误：本地测试用的http://localhost:10001仅适配本地环境，部署到线上后前端页面通过https://example.com访问，跨域+协议不匹配直接拦截WebSocket握手，Socket.IO自动降级为轮询模式。
• Nginx反向代理配置缺失必要参数：现有配置缺少X-Forwarded-Proto头传递原始请求的https协议，同时Connection头的单引号在部分Nginx版本中会解析错误，也会导致握手失败。
• 传输协议配置不匹配：强制指定transports: ['websocket']时，前两个问题导致握手返回400错误，无法正常建立连接。

第一步：修改客户端连接配置 #

根据环境自动适配连接地址，同时指定传输优先级：

import VueSocketIO from 'vue-socket.io'

Vue.use(
    new VueSocketIO({
        debug: true,
        // 生产环境替换为实际线上域名，https协议会自动适配wss
        connection: process.env.NODE_ENV === 'production' ? 'https://example.com' : 'http://localhost:10001',
        options: {
            transports: ['websocket', 'polling'] // 优先走WebSocket，失败再降级为轮询
        },
        vuex: {
            store,
            actionPrefix: 'SOCKET_',
            mutationPrefix: 'SOCKET_',
        },
    })
)

第二步：修正Nginx配置 #

替换原有的/socket.io配置段：

location /socket.io {
    proxy_pass http://localhost:10001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade"; # 改用双引号避免解析错误
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme; # 传递原始请求协议
    proxy_cache_bypass $http_upgrade;
    proxy_read_timeout 86400; # 避免长连接被Nginx主动断开
}

修改完成后执行nginx -s reload重载配置生效。

第三步：调整服务端配置 #

明确SocketIO初始化参数，避免默认适配出错：

socketio = SocketIO(
    app, 
    cors_allowed_origins="*", 
    logger=True, 
    engineio_logger=True, # 开启引擎日志，方便后续排查握手相关错误
    async_mode="threading" # 明确指定异步模式
)

如果对安全性要求较高，可以把cors_allowed_origins参数替换为实际线上域名https://example.com，限制跨域来源。

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