Nginx反向代理Socket.IO连接失败问题求助

阿华AIGC实验室

2026-5-27

解决Nginx反向代理Node.js-Socket.IO应用的问题

没问题，我来帮你搞定这个Socket.IO反向代理的坑！Socket.IO和普通HTTP应用不一样，它会先通过HTTP握手，然后升级到WebSocket长连接，所以Nginx配置里必须专门处理这些细节，否则连接会失败。

第一步：修正你的Nginx配置

首先假设你的Node.js Socket.IO服务运行在localhost:3000（如果不是，替换成你的实际端口），下面是能正常工作的Nginx server配置块：

server {
    listen 80;
    server_name localhost; # 也可以换成你的实际域名

    location / {
        # 代理托管你的客户端HTML文件
        root /path/to/your/html/files;
        index index.html;
    }

    location /socket.io/ {
        # 反向代理Socket.IO请求到Node服务
        proxy_pass http://localhost:3000;
        # Socket.IO依赖HTTP/1.1特性，必须开启
        proxy_http_version 1.1;
        # 核心：处理WebSocket连接升级请求
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        # 传递必要请求头，确保Socket.IO能正确识别客户端
        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;
        # 长连接超时设置，避免Nginx主动断开连接
        proxy_connect_timeout 7d;
        proxy_send_timeout 7d;
        proxy_read_timeout 7d;
    }
}

第二步：调整客户端代码（可选但推荐）

如果你的HTML文件是通过Nginx（80端口）提供的，客户端代码可以简化，不用硬写地址，直接用同源路径更灵活：

<html>
<head>
    <!-- 让Nginx代理这个脚本请求到Node服务 -->
    <script src="/socket.io/socket.io.js"></script>
    <script>
        // 自动从当前域名/端口获取Socket.IO服务，无需硬编码地址
        var socket = io();
        socket.on('welcome', function(data){
            console.log('Server says:' + data);
            socket.emit('client-response', 'thank you!');
        });
    </script>
</head>
<body>
    Socket.io
</body>
</html>

如果你是本地下载了socket.io.js文件，只要把它放在Nginx的静态文件目录里，保证路径正确即可。

第三步：验证与排查

重启Nginx让配置生效：执行sudo nginx -s reload
确认Node.js服务正在运行，且监听端口和Nginx配置里的proxy_pass一致
打开浏览器控制台查看Network标签：
- 首先会看到GET /socket.io/?EIO=4&transport=polling...的请求，状态应为200
- 之后会升级到WebSocket连接，出现ws://localhost/socket.io/?EIO=4&transport=websocket...的请求，状态为101 Switching Protocols
如果仍有问题，检查Nginx错误日志（通常在/var/log/nginx/error.log）和Node服务日志，定位具体报错

内容的提问来源于stack exchange，提问作者Ümit Aparı