部署Node/Express+React项目时Socket.IO生产环境无法通信

云上老周

2026-8-29

问题根因

生产环境连接失败是几个核心配置错误共同导致的：

服务端HTTP实例未绑定Express应用
你贴的服务端代码里createServer()没有传入初始化好的express实例，等于Express服务和Socket.io绑定的HTTP服务完全独立，定义的app根本没有挂载到8080端口的HTTP服务上，静态资源托管、接口路由全不生效。本地能跑通大概率是本地调试时写了正确传参的版本，迁移到生产时改漏了这行代码。
未配置Socket.io跨域规则
本地构建后同域部署不存在跨域问题，但生产环境如果前后端端口、域名不一致，又没有显式配置CORS允许来源，WebSocket握手请求会直接被浏览器拦截。
反向代理未配置WebSocket支持
绝大多数生产部署不会直接暴露8080端口对外，会用Nginx等反向代理把80/443端口的请求转发到后端服务，默认代理配置不会转发Connection: Upgrade和Upgrade: websocket头，会直接断开Socket.io的长连接。
客户端默认连接地址不匹配代理场景
你客户端写的io()默认会连接当前页面访问的域名+端口，如果生产环境前端走443/80端口，Socket.io服务没有通过反向代理暴露在同域默认端口下，又没有显式指定连接地址，自然无法连通。

正确配置步骤

首先修正服务端代码：

import express from "express";
const app = express();
// 托管React构建后的静态资源，确保同域部署时前端页面可正常访问
app.use(express.static('build'));

import { createServer } from "http";
import { Server } from "socket.io";
// 必须把express实例传入createServer，绑定到同一个HTTP服务
const httpServer = createServer(app);
// 配置CORS，根据实际生产域名修改允许来源
const io = new Server(httpServer, {
  cors: {
    origin: "https://你的生产域名", // 同域部署可删除整段cors配置
    methods: ["GET", "POST"]
  },
  path: "/socket.io/"
});

const PORT = process.env.PORT || 8080;
httpServer.listen(PORT, () => {
  console.log(`服务运行在${PORT}端口`);
});

// Socket连接逻辑
let connections = 0;
io.on("connection", (socket) => {
  connections++;
  console.log(`当前连接数：${connections}`);
  socket.on("disconnect", () => {
    connections--;
  })
});

然后匹配客户端配置：

如果是同域部署，且反向代理已经把/socket.io/路径的请求转发到后端8080端口，直接用const socket = io();即可，不需要额外传参。
如果没有做路径代理，Socket服务单独跑在其他端口/域名，显式传入连接地址：

import { io } from "socket.io-client";
// 替换成实际的Socket服务地址，不要带末尾斜杠
const socket = io("https://你的生产域名", {
  // 和服务端path配置保持一致
  path: "/socket.io/",
  transports: ["websocket", "polling"]
});
export default socket;

如果用了Nginx反向代理，需要在对应服务配置中添加WebSocket转发规则：

location /socket.io/ {
  proxy_pass http://127.0.0.1:8080;
  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;
}

排查顺序

先修正服务端createServer(app)的传参问题，重启服务后访问服务器8080端口，确认能正常打开React页面，验证HTTP服务绑定正常。
临时放开服务器防火墙的8080端口，客户端直接连http://服务器IP:8080测试连通性：能连通说明是反向代理配置问题，连不通检查服务端CORS和端口监听规则。
直连连通后再配置反向代理规则，关闭对外暴露的8080端口，用同域方式连接即可。

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