本文详解在 Socket.IO 多文件并发上传场景下，为何 socket.on('upload-progress') 会错误关联视频索引，并提供基于动态事件名、闭包优化及服务端增强的完整解决方案，确保每个视频的进度与 ID 精准更新到对应表单项。
本文详解在 socket.io 多文件并发上传场景下，为何 `socket.on('upload-progress')` 会错误关联视频索引，并提供基于动态事件名、闭包优化及服务端增强的完整解决方案，确保每个视频的进度与 id 精准更新到对应表单项。
在基于 Socket.IO 的多视频上传系统中，一个常见却隐蔽的陷阱是：当多个视频并行上传时，若在循环或多次调用中重复注册相同的全局事件监听器（如 'upload-progress'），会导致所有监听器共享同一个闭包作用域中的 index 变量——而该变量在异步执行时早已被后续迭代覆盖，最终所有进度更新都写入最后一个视频的索引位置。根本原因在于 JavaScript 事件监听器的异步执行时机与 var/函数作用域 index 的生命周期错位，而非 Socket.IO 本身缺陷。
✅ 正确方案：为每个上传任务创建独立事件通道
最简洁、可靠且无需修改服务端逻辑的方式，是为每个视频上传绑定唯一事件名，避免监听器污染与索引混淆：
async function handleUploadLectureVideo({ files }: any, index: number) {
const file = files[0];
const formData = new FormData();
formData.append("file", file);
formData.append("name", file.name);
// 生成唯一事件标识（推荐使用 UUID 或时间戳 + index 组合）
const uploadId = `upload-${Date.now()}-${index}`;
socket.emit("upload-file", {
file,
fileMeta: { originalName: file.name },
name: file.name,
uploadId, // ? 关键：透传唯一标识至后端
});
// ✅ 使用动态事件名，确保监听器一一对应
const progressEvent = `upload-progress-${uploadId}`;
const successEvent = `upload-success-${uploadId}`;
// 监听专属进度事件
socket.once(progressEvent, (data: number) => {
console.log(`Progress for video ${index}: ${data}%`);
setValue(`courseLectures.${index}.uploadingProgress`, data);
});
// 监听专属成功事件（使用 once 避免重复注册残留）
socket.once(successEvent, (data: any) => {
setValue(`courseLectures.${index}.lectureVideo`, data.id);
});
}⚠️ 注意事项：
- 必须使用 socket.once() 而非 socket.on()，防止多次调用导致同一事件被重复监听，引发内存泄漏与逻辑错乱；
- uploadId 需保证全局唯一性（避免仅用 index，因重试或快速连续上传可能导致冲突），推荐组合 Date.now() 与 index，或使用 crypto.randomUUID()（现代环境）；
- 前端需与后端约定：服务端在 emit 进度/成功事件时，必须携带相同 uploadId。
? 后端同步改造（NestJS）
为支持前端动态事件机制，需在服务端 handleFileUpload 中接收并透传 uploadId，并在 emit 时附加该标识：
// NestJS Controller
async handleFileUpload(
@MessageBody() data: any,
@ConnectedSocket() client: Socket
) {
const { file, fileMeta, name, uploadId } = data; // ✅ 解构 uploadId
const filename = this.getCompleteFileName(fileMeta);
const completePath = join('video-lectures', filename);
await promises.writeFile(completePath, file);
this.vimeoClient.upload(
completePath,
{ name },
async (uri: string) => {
const video = new Video();
video.url = uri;
const result = await this.videoRepository.save(video);
client.emit(`upload-success-${uploadId}`, result); // ✅ 动态事件名
},
(bytesUploaded: number, bytesTotal: number) => {
const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
client.emit(`upload-progress-${uploadId}`, parseFloat(percentage)); // ✅ 动态事件名
},
(error) => {
console.error('Upload failed:', error);
client.emit(`upload-failed-${uploadId}`, error);
}
);
}? 替代方案：统一监听 + payload 标识（适合大规模上传）
若上传数量极大（如 >50），动态注册大量事件可能影响性能，可改用单监听器 + payload 携带元数据方式：
// ✅ 全局仅注册一次（建议在组件初始化时）
useEffect(() => {
socket.on('upload-progress', ({ uploadId, progress }) => {
// 根据 uploadId 查找对应 index（例如从 ref 映射表中获取）
const index = uploadIdToIndexMap.get(uploadId);
if (index !== undefined) {
setValue(`courseLectures.${index}.uploadingProgress`, progress);
}
});
socket.on('upload-success', ({ uploadId, videoId }) => {
const index = uploadIdToIndexMap.get(uploadId);
if (index !== undefined) {
setValue(`courseLectures.${index}.lectureVideo`, videoId);
}
});
return () => {
socket.off('upload-progress');
socket.off('upload-success');
};
}, []);
// 在 handleUploadLectureVideo 中维护映射关系
const uploadId = `upload-${Date.now()}-${index}`;
uploadIdToIndexMap.set(uploadId, index);✅ 总结
| 方案 | 适用场景 | 优势 | 注意点 |
|---|---|---|---|
| 动态事件名（推荐） | 中小规模并发（≤20 视频） | 隔离性强、逻辑清晰、调试友好 | 务必用 once，确保 uploadId 唯一 |
| 统一监听 + payload 映射 | 大规模或需集中管理的场景 | 减少事件监听器数量，利于状态聚合 | 需维护 uploadId ↔ index 映射表，注意清理 |
无论采用哪种方式，核心原则不变：禁止在循环/多次调用中重复注册同名全局事件监听器。通过显式绑定上下文（事件名或 payload），即可彻底解决多上传任务中进度与索引错位的经典问题。
