Docker部署React应用WebSocket连接失败排查求助

核心问题分析 #

浏览器受同源策略限制，而容器内的wscat、本地运行的应用（localhost域名浏览器会放宽CORS限制）不受此约束，所以问题大概率出在WebSocket服务的CORS配置缺失/错误，或者是Docker网络、反向代理的配置问题。

1. 检查WebSocket服务的CORS配置 #

如果你的WebSocket服务用的是Node.js的ws库，必须显式配置允许React应用的域名：

const WebSocket = require('ws');
const wss = new WebSocket.Server({
  port: 8080,
  verifyClient: (info, done) => {
    // 替换成你的React应用实际域名，本地开发用http://localhost:3000
    const allowedOrigins = ['http://localhost:3000', 'http://your-prod-domain.com'];
    if (allowedOrigins.includes(info.origin)) {
      done(true);
    } else {
      done(false, 403, '域名未被允许');
    }
  }
});

其他后端框架的配置注意点：

• FastAPI：要给应用添加CORSMiddleware，同时确保允许WebSocket的OPTIONS预检请求
• Spring Boot：通过全局CORS配置或@CrossOrigin注解，开放WebSocket接口的跨域权限

2. 核对Docker Compose的网络与环境变量 #

• WebSocket服务的端口必须正确映射到宿主机，否则浏览器无法访问容器内的服务
• React应用的REACT_APP_WS_URL必须指向宿主机的IP/域名，不能用容器内部的服务名（比如ws-server:8080），因为浏览器是从宿主机发起请求的
  示例docker-compose.yml配置：

services:
  ws-server:
    build: ./ws-server
    ports:
      - "8080:8080" # 宿主机端口映射到容器端口
  react-client:
    build: ./react-client
    ports:
      - "3000:3000"
    environment:
      # 本地开发用localhost，生产用服务器公网IP/域名
      - REACT_APP_WS_URL=ws://localhost:8080/ws

3. 排查反向代理（如Nginx）的CORS配置 #

如果用了Nginx做反向代理，必须同时配置WebSocket转发和CORS头，否则浏览器会拦截连接：

server {
  listen 80;
  server_name your-domain.com;

  location /ws {
    proxy_pass http://ws-server:8080;
    # 必须开启的WebSocket转发配置
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    # CORS相关配置
    proxy_set_header Origin $http_origin;
    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Credentials true;
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS, WEBSOCKET";
    add_header Access-Control-Allow-Headers "Upgrade, Connection, Origin";
    # 处理OPTIONS预检请求，直接返回204
    if ($request_method = OPTIONS) {
      return 204;
    }
  }
}

4. 浏览器端直接验证连接 #

打开浏览器开发者工具（F12），在Console标签执行以下代码，排除react-use-websocket的封装问题：

const ws = new WebSocket('你的WS地址');
ws.onopen = () => console.log('连接成功！');
ws.onerror = (err) => console.error('连接出错：', err);
ws.onclose = () => console.log('连接关闭');

如果这段代码能成功连接，说明是react-use-websocket的配置问题，检查是否正确传入了url，或者是否有额外的options（比如protocols、headers）导致连接失败。

5. 查看浏览器网络日志定位错误 #

在开发者工具的Network标签，过滤WebSocket请求，查看：

• 请求头的Origin是否是React应用的域名
• 响应头是否包含Access-Control-Allow-Origin，且值与Origin匹配
• 控制台的具体错误信息，比如Access-Control-Allow-Origin header missing直接指向CORS配置问题，Invalid URL则是环境变量配置错误

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