WebSocket不能直接传文件，必须用“HTTP上传+WebSocket推送”混合方案，因浏览器File对象无法原样发送、缺乏校验与断点续传机制、丢失multipart元数据，且服务端需额外实现流控与状态管理。
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 会话之间的桥梁：
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 前端在发起
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;
<pre class="brush:php;toolbar:false;"> 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 会持续膨胀。这个细节在单机开发时看不出问题，上线多实例后立刻暴露。
