WebSocket上传进度实时显示技巧

本文深入剖析了WebSocket无法直接上传文件的根本原因，揭示了浏览器限制、协议语义缺失及服务端复杂度等关键陷阱，并系统性地提出“HTTP上传+WebSocket推送”的混合方案作为唯一稳健解法；文章以uploadId为状态枢纽，详解前后端如何协同实现进度实时反馈——从前端生成唯一标识、绑定WebSocket连接，到后端通过Multer自定义Storage捕获字节级进度、借助事件总线解耦推送逻辑，再到容错设计（心跳保活、连接中断清理、TTL兜底），覆盖开发中极易忽略却至关重要的细节，为构建高可用、可维护的大文件上传体验提供了一套经过实践检验的完整技术路径。

WebSocket 本身不能直接传文件，也不能直接获取 HTTP 上传进度——必须用“HTTP 上传 + WebSocket 推送”混合方案，否则会掉进协议语义缺失、浏览器限制、重传逻辑失控的坑里。

为什么不能用 WebSocket 直接 send(File)？

浏览器的 File 对象无法被 socket.send() 原样发送；手动读取 FileReader 或 stream.getReader() 分片再发，会立刻暴露以下问题：

• 没有内置校验（如 Content-MD5 或分片 hash），出错难定位
• 丢失 multipart/form-data 的字段边界和元数据（比如 filename、content-type）
• 断网重连后无法断点续传——WebSocket 协议不定义“分片序号”或“已接收集合”
• 服务端需额外实现流控、合并、临时存储逻辑，复杂度远超 Multer 或 busboy

uploadId 是前后端状态绑定的唯一钥匙

所有进度推送都依赖一个可传递、可查、可清理的标识。它不是随机字符串，而是上传请求与 WebSocket 会话之间的桥梁：

• 前端在发起 fetch('/upload', {method: 'POST', body: formData}) 前，先生成 uploadId = Date.now() + '-' + Math.random().toString(36).substr(2, 9)
• 把 uploadId 作为字段塞进 formData.append('uploadId', uploadId)
• 同时用该 uploadId 初始化 WebSocket 连接：new WebSocket(`ws://host/progress?uploadId=${uploadId}`)
• 后端收到上传请求后，立即在内存 Map 或 Redis 中存入 {[uploadId]: {startTime: Date.now(), progress: 0, status: 'uploading'}}
• 后续所有进度更新（包括完成、失败）都通过查找这个 uploadId 定位目标客户端

Multer 自定义 Storage 是进度捕获的关键切口

Multer 的默认 DiskStorage 不暴露字节级写入钩子，必须替换为自定义 storage 引擎才能实时上报进度：

const storage = multer.memoryStorage(); // 或自定义 writeStream
const upload = multer({
  storage: {
    _handleFile: (req, file, cb) => {
      const uploadId = req.body.uploadId;
      const total = parseInt(req.headers['content-length'], 10);
      let uploaded = 0;
  const stream = file.stream;
  stream.on('data', chunk => {
    uploaded += chunk.length;
    const percent = Math.round((uploaded / total) * 100);
    // 推送：wss.clients.forEach(client => {
    //   if (client.uploadId === uploadId) client.send(JSON.stringify({ type: 'progress', percent }))
    // })
  });

  stream.on('end', () => cb(null, { ...file, path: 'in-memory' }));
}
}
});

• 注意：真实项目中应避免在 _handleFile 内直接操作 wss.clients，推荐改用事件总线（如 EventEmitter）解耦
• 若用 DiskStorage，需监听 fs.createWriteStream 的 'write' 和 'drain' 事件，但要注意 Node.js 版本差异对 drain 触发时机的影响
• 务必对 uploadId 做白名单校验，防止恶意构造参数污染状态映射表

前端监听要防重复绑定和连接中断残留

WebSocket 连接不稳定是常态，前端不能假设一次 connect 就永久有效：

• 在 socket.onopen 后立即发一条 {"action":"bind","uploadId":"xxx"}，服务端收到才正式建立映射
• 监听 socket.onclose 和 socket.onerror，触发时清除本地进度状态，并提示用户“连接已断开，正在重试…”
• 不要在 onmessage 里无条件更新 document.getElementById('progress').value，先校验 data.uploadId === currentUploadId
• 设置 socket.heartbeat = setInterval(() => socket.send('ping'), 25000)，后端对应返回 'pong'，超时未响应则主动重连

最易被忽略的是 uploadId 的 TTL 清理——如果用户上传中途关闭页面，后端不会自动知道，必须靠定时器或 Redis 过期键来兜底，否则内存或 Redis 会持续膨胀。这个细节在单机开发时看不出问题，上线多实例后立刻暴露。

今天关于《WebSocket上传进度实时显示技巧》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！