在WSL2、Docker及Nginx反向代理下配置Vite HMR遇阻求助

1. 确认Vite服务是否正常启动 #

• 进入前端Pod：docker exec -it <前端Pod名称/ID> sh
• 检查Vite进程：ps aux | grep vite，无进程则说明服务未启动，需核对Dockerfile.dev的启动命令（如quasar dev）是否正确，或是否存在启动依赖缺失
• 查看容器实时日志：docker logs -f <前端Pod名称/ID>，排查启动阶段是否有报错信息

2. 校验Vite监听配置 #

• 检查quasar.config.js中的Vite服务配置，确保：

  build: {
    vite: {
      server: {
        host: '0.0.0.0', // 必须绑定0.0.0.0，否则仅容器内部可访问
        port: 8081,
        hmr: {
          host: 'localapp.com', // 与浏览器访问的自定义域名一致
          protocol: 'wss' // 适配Nginx的HTTPS环境
        }
      }
    }
  }
  

• 在前端Pod内执行netstat -tulpn | grep 8081（需先安装net-tools：apt install net-tools），确认进程是否监听0.0.0.0:8081，而非仅127.0.0.1

3. 检查Nginx的WebSocket转发配置 #

• 确保Nginx正确转发HMR的WebSocket请求，示例配置：

  server {
    listen 443 ssl;
    server_name localapp.com;
    # SSL证书配置省略
  
    # 转发HMR请求核心配置
    location /__vite_hmr {
      proxy_pass http://<前端服务名>:8081; // 对应docker-compose中的前端服务名称
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_set_header Host $host;
    }
  
    # 常规页面转发
    location / {
      proxy_pass http://<前端服务名>:8081;
      proxy_set_header Host $host;
    }
  }
  

• 验证Nginx配置有效性：docker exec -it <NginxPod名称/ID> nginx -t，若有错误修正后重启：docker exec -it <NginxPod名称/ID> nginx -s reload

4. 排查Docker网络与DNS问题 #

• 确认前端Pod与NginxPod处于同一Docker网络，docker-compose.yml需配置共用网络：

  networks:
    app-network:
      driver: bridge
  
  services:
    frontend:
      networks:
        - app-network
    nginx:
      networks:
        - app-network
  

• 在NginxPod内执行ping <前端服务名>，检查是否能解析到前端Pod的IP（如10.90.0.4），解析失败则需检查网络配置
• 验证WSL2与Windows的hosts配置：ping localapp.com，确认指向NginxPod映射的WSL2 IP

5. 端口转发与防火墙校验 #

• 核对docker-compose.yml中Nginx的端口映射：

  ports:
    - "443:443"
    - "80:80"
  

• 临时关闭WSL2的ufw防火墙测试：sudo ufw disable，同时检查Windows防火墙是否允许443端口入站
• 用工具测试WebSocket连接：安装wscat后执行wscat -c wss://localapp.com/__vite_hmr，查看是否能成功握手

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