大文件上传？我用分片上传+断点续传彻底解决了！

前端开发者们，让我们一起告别传统文件上传的痛点！

作为一名前端开发者，相信大家都遇到过这样的场景：用户需要上传一个几百兆甚至几个G的大文件，你看着进度条缓慢前进，心里默默祈祷不要中途出错，因为一旦失败，用户就得从头再来...

这种体验实在太糟糕了！但别担心，今天我要分享的分片上传+断点续传方案，将彻底解决这些问题！

为什么传统文件上传在大文件面前如此脆弱？

在深入技术方案前，先来吐槽一下传统文件上传的痛点：

• 网络不稳定：上传过程中网络波动导致失败
• 服务器限制：请求超时、请求体大小限制
• 用户体验差：进度条卡住、失败需重新上传
• 资源浪费：已上传的部分因失败而白费

曾经有个项目，用户需要上传设计稿源文件，平均大小都在1GB以上。最初使用传统上传方式，失败率高达30%！用户怨声载道，产品经理天天追着研发优化，那段时间简直是研发的噩梦...

革命性解决方案：分片上传

什么是分片上传？

想象一下，你要搬一台钢琴到五楼。如果一个人硬扛，不仅困难还容易半路失手。但如果把钢琴拆成多个部件，多人协作搬运，就轻松多了！

分片上传也是同样道理：将大文件切成多个小片段，分别上传，最后在服务器端组装。

// 分片大小通常为1-5MB
const CHUNK_SIZE = 1024 * 1024 * 5; // 5MB

// 计算总分片数
const totalChunks = Math.ceil(file.size / CHUNK_SIZE);

核心技术优势

1. 稳定性：单个分片失败不影响其他分片，只需重试失败的分片
2. 高效性：可以并行上传多个分片，充分利用带宽
3. 可控性：精确控制上传过程，支持暂停、恢复
4. 容错性：网络波动只影响当前分片，不会导致整个上传失败

实战：从零实现分片上传系统

下面我就带大家一步步实现完整的解决方案，我会重点讲解其中的难点和优化技巧。

1. 文件哈希计算：识别文件的唯一身份证

为什么要计算文件哈希？两个原因：

• 秒传功能：如果服务器已有相同文件，直接返回成功
• 分片标识：确保分片属于正确的文件

Web Worker 的妙用

哈希计算是CPU密集型任务，如果在主线程进行会导致页面卡顿。Web Worker 是我们的救星！

// hash.worker.ts
export type HashWorkerIn = {
    type: 'HASH';
    file: File;
    chunkSize: number;
}

export type HashWorkerOut = {
    type: 'DONE';
    hash: string;
} | {
    type: 'PROGRESS';
    progress: number;
}

// SHA-256 计算函数
async function sha256ArrayBuffer(buf: ArrayBuffer): Promise<string> {
  const hashBuffer = await crypto.subtle.digest('SHA-256', buf);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
}

self.onmessage = async (e: MessageEvent<HashWorkerIn>) => {
    const msg = e.data
    if (msg.type === 'HASH') {
        const { file, chunkSize } = msg;
        const total = Math.ceil(file.size / chunkSize);
        
        // 将文件切片并计算整体哈希
        const chunks: ArrayBuffer[] = [];
        for (let i = 0; i < total; i++) {
            const start = i * chunkSize;
            const end = Math.min(file.size, start + chunkSize);
            const chunk = await file.slice(start, end).arrayBuffer();
            chunks.push(chunk);
            
            // 汇报进度
            (self as any).postMessage({
                type: 'PROGRESS',
                progress: (i + 1) / total,
            } as HashWorkerOut);
        }
        
        // 计算整体文件的哈希
        const whole = new Blob(chunks);
        const hash = await sha256ArrayBuffer(await whole.arrayBuffer());
        
        (self as any).postMessage({
            type: 'DONE',
            hash,
        } as HashWorkerOut);
    }
}

这里有个技术细节：为什么我要先把文件切成片，再用Blob组合起来计算哈希，而不是直接计算整个文件的哈希？

答案是：一致性！这样确保前端计算的哈希与服务器重组文件后的哈希完全一致。

2. React 前端实现：优雅的上传管理

useRef 的高级用法

在这个项目中，useRef 发挥了巨大作用，它不仅仅用于DOM引用：

const Upload = () => {
    const workerRef = useRef<Worker | null>(null);
    const abortRef = useRef<AbortController | null>(null);
    const pausedRef = useRef<boolean>(false);
    
    // 1. workerRef - 保持Web Worker实例
    // 2. abortRef - 控制上传请求的取消
    // 3. pausedRef - 暂停状态，避免闭包问题
}

特别提醒 ：pausedRef 的使用很关键。如果直接用useState管理暂停状态，由于闭包问题，在异步函数中获取的状态可能不是最新的。useRef可以确保始终获取最新值。

并发控制：Promise.all + 递归的完美配合

并发控制是分片上传的核心难点之一。既要充分利用浏览器并行能力，又要避免同时发起过多请求导致浏览器卡死。

const startUpload = async () => {
    // ... 初始化代码
    
    const queue: number[] = [];
    for (let i = 0; i < totalChunks; i++) {
        if (!uploaded.has(i)) {
            queue.push(i); // 创建待上传队列
        }
    }
    
    // 并发控制核心逻辑
    const workers: Promise<void>[] = [];
    
    const next = async () => {
        if (pausedRef.current) return; // 暂停检查
        
        const idx = queue.shift();
        if (idx === undefined) return;
        
        try {
            await uploadedChunk(idx, abortRef.current!.signal);
            done++;
            setProgress(Math.floor((done / totalChunks) * 100));
        } finally {
            if (queue.length) {
                await next(); // 递归继续处理下一个
            }
        }
    }
    
    // 启动指定数量的并发worker
    for (let c = 0; c < Math.min(MAX_CONCURRENT, queue.length); c++) {
        workers.push(next());
    }
    
    await Promise.all(workers); // 等待所有worker完成
}

这个并发控制模式很精妙！它创建了固定数量的"工人"，每个工人完成当前任务后，自动从队列中取下一个任务，直到队列清空。

上传进度计算的艺术

进度计算看似简单，实则有很多细节：

// 错误做法：直接基于已上传字节数计算
// 问题：暂停、失败重试会导致进度回退，用户体验差

// 正确做法：基于成功上传的分片数计算
let done = uploaded.size; // 从服务器获取的已上传分片数
setProgress(Math.floor((done / totalChunks) * 100));

// 每成功上传一个分片
done++;
setProgress(Math.floor((done / totalChunks) * 100));

3. 服务端设计：RESTful API 的优雅实践

接口设计哲学

我设计了三个核心接口，符合RESTful规范：

1. 初始化接口 POST /api/upload/init - 文件上传前的握手
2. 分片上传接口 PUT /api/upload/chunk - 实际上传分片
3. 合并接口 POST /api/upload/merge - 合并所有分片

自定义请求头的妙用

在分片上传接口中，我使用了自定义请求头：

const res = await fetch('/api/upload/chunk', {
    method: 'PUT',
    headers: {
        "x-file-hash": hash,           // 文件哈希
        "x-chunk-index": index.toString(), // 分片索引
    },
    body: chunk, // 分片二进制数据
    signal
});

为什么不用JSON格式在body中传递这些元数据？因为：

• 性能：服务端无需解析整个请求体就能获取元数据
• 清晰：分离元数据和实际文件内容
• 标准：符合HTTP规范，元数据放header，数据放body

初始化接口：秒传与断点续传的基石

export async function POST(req: NextRequest) {
    const {
        fileHash,
        fileName,
        fileSize,
        chunkSize,
        totalChunks
    } = await req.json();
    
    ensureUploadDir(fileHash);
    
    // 秒传检查：文件是否已存在
    if (fileAlreadyExist(fileHash, fileName)) {
        return NextResponse.json({
            complete: true,
            uploaded: [],
            message: "秒传,文件已存在"
        });
    }
    
    // 断点续传：获取已上传的分片
    const existed = readMeta(fileHash);
    const uploaded = listUploadedChunks(fileHash);
    
    // 更新元数据
    const meta = {
        fileName,
        fileSize,
        chunkSize,
        totalChunks,
        uploadedChunks: uploaded,
        complete: false,
    }
    writeMeta(fileHash, { ...(existed || {}), ...meta });
    
    return NextResponse.json({
        complete: false,
        uploaded, // 返回已上传的分片列表
        message: "初始化成功"
    })
}

分片上传：可靠的存储机制

export async function PUT(req: NextRequest) {
    const chunkIndex = Number(req.headers.get('x-chunk-index'));
    const fileHash = req.headers.get('x-file-hash');

    // 获取二进制数据
    const buf = Buffer.from(await req.arrayBuffer());
    
    // 保存分片
    await saveChunk(fileHash, chunkIndex, buf);
    
    // 更新元数据
    const meta = readMeta(fileHash);
    if (meta) {
        // 使用Set去重并排序
        const set = new Set([...(meta.uploadedChunks ?? []), chunkIndex]);
        meta.uploadedChunks = Array.from(set).sort((a, b) => a - b);
        writeMeta(fileHash, meta);
    }

    return NextResponse.json({ ok: true });
}

文件合并：从分片到完整文件

export async function mergeChunks(
    fileHash: string, 
    fileName: string, 
    totalChunks: number
) {
    const { chunkDir } = getUploadDir(fileHash);
    const finalPath = finalFilePath(fileHash, fileName);
    const stream = createWriteStream(finalPath);
    
    // 按顺序合并所有分片
    for (let i = 0; i < totalChunks; i++) {
        const chunkPath = join(chunkDir, `${i}.part`);
        if (!existsSync(chunkPath)) {
            throw new Error(`chunk ${i} 缺失`);
        }
        const chunk = readFileSync(chunkPath);
        stream.write(chunk);
    }
    
    stream.end();
    
    return new Promise((resolve, reject) => {
        stream.on('error', reject);
        stream.on('finish', () => resolve(finalPath));
    });
}

4. 服务端文件管理：专业级的存储方案

目录结构设计

uploads/
  └── {fileHash}/           # 以文件哈希命名的目录
       ├── meta.json        # 元数据文件
       ├── final-file.ext   # 最终合并的文件
       └── chunks/          # 分片存储目录
            ├── 0.part
            ├── 1.part
            └── ...

这种结构的好处：

• 隔离性：每个文件的资源独立存放
• 易清理：按文件哈希管理，清理方便
• 可追溯：完整的元数据和分片可追溯

元数据管理

export type Meta = {
    fileName: string;        // 原始文件名
    fileSize: number;        // 文件大小
    chunkSize: number;       // 分片大小
    totalChunks: number;     // 总分片数
    uploadedChunks: number[]; // 已上传的分片索引
    complete: boolean;       // 是否已完成
    finalPath?: string;      // 最终文件路径
}

深入难点：并发控制的精妙之处

让我再深入讲解一下并发控制这个核心难点。很多开发者在这里容易踩坑。

常见错误做法

// 错误示例：直接使用Promise.all并发所有分片
const uploadPromises = chunks.map((chunk, index) => 
    uploadChunk(chunk, index)
);
await Promise.all(uploadPromises);

这种写法的问题：

• 瞬间创建大量HTTP请求，浏览器可能崩溃
• 无法控制并发数，小文件还好，大文件（几百个分片）就惨了
• 无法实现暂停、取消功能

正确解决方案

我采用的"工人模式"既优雅又实用：

const next = async () => {
    if (pausedRef.current) return; // 可中断
    
    const idx = queue.shift();
    if (idx === undefined) return;
    
    try {
        await uploadedChunk(idx, abortRef.current!.signal);
        // 更新进度...
    } finally {
        if (queue.length) {
            await next(); // 递归继续
        }
    }
}

// 启动有限数量的工人
for (let c = 0; c < Math.min(MAX_CONCURRENT, queue.length); c++) {
    workers.push(next());
}

await Promise.all(workers);

这个模式的好处：

• 资源可控：始终只有固定数量的并发请求
• 可中断：通过ref控制可随时暂停
• 自动延续：工人自动从队列取任务，直到完成所有工作

TypeScript 实战技巧

在这个项目中，TypeScript发挥了巨大作用，特别是在复杂的数据类型和跨线程通信中。

Worker 线程通信类型安全

// 定义精确的输入输出类型
export type HashWorkerIn = {
    type: 'HASH';
    file: File;
    chunkSize: number;
}

export type HashWorkerOut = {
    type: 'DONE';
    hash: string;
} | {
    type: 'PROGRESS';
    progress: number;
}

// 使用时获得完整的类型提示和检查
worker.onmessage = (e: MessageEvent<HashWorkerOut>) => {
    const msg = e.data;
    if (msg.type === 'PROGRESS') {
        // TypeScript知道这里msg有progress属性
        setStatus(`计算中 ${(msg.progress * 100).toFixed(2)}%`);
    }
    if (msg.type === 'DONE') {
        // TypeScript知道这里msg有hash属性
        setHash(msg.hash);
    }
};

非空断言的合理使用

// 在确实不为空的情况下使用非空断言
const chunk = file!.slice(start, end);

// 比可选链更精准的表达意图
// file?.slice 表示file可能为null/undefined
// file!.slice 表示我确信这里file不为空

性能优化实战

useCallback 的合理使用

// 优化前：每次渲染都创建新函数
const handleFile = (file: File) => {
    // 处理逻辑
};

// 优化后：函数缓存，避免不必要的重新渲染
const handleFile = useCallback(async (file: File) => {
    setFile(file);
    setStatus('计算哈希中');
    workerRef.current?.postMessage({
        type: 'HASH',
        file,
        chunkSize: CHUNK_SIZE,
    } as HashWorkerIn);
}, []);

进度计算的性能考虑

// 避免过于频繁的状态更新
// 错误做法：每个字节更新一次进度 - 导致界面卡顿

// 正确做法：基于分片更新进度
let done = uploaded.size;
setProgress(Math.floor((done / totalChunks) * 100));

// 只有分片完成时才更新进度，平衡精确度和性能

错误处理与用户体验

友好的错误提示

try {
    await Promise.all(workers);
    if (pausedRef.current) {
        setStatus('上传已暂停');
        return;
    }
    setStatus("合并分片");
    const r = await mergeAll();
    setStatus(r?.ok ? '上传完成' : '合并失败');
} catch (e: any) {
    if (e?.name === 'AbortError') {
        setStatus('上传已暂停');
        return;
    } else {
        console.error('上传失败', e);
        // 给用户友好的错误提示，而不是原始错误对象
        setStatus(e?.message || '上传错误，请重试');
    }
}

暂停恢复机制

const pause = () => {
    pausedRef.current = true;
    abortRef.current?.abort(); // 中止进行中的请求
}

const resume = async () => {
    if (!file || !hash) return;
    
    setStatus('继续上传...');
    // 重新初始化，获取最新的已上传分片
    await startUpload();
}

部署与生产环境考虑

安全增强建议

1. 文件类型验证：服务端验证文件类型和扩展名
2. 大小限制：控制单个文件和总上传大小
3. 频率限制：防止恶意上传
4. 病毒扫描：集成病毒扫描服务

扩展性考虑

1. 分布式存储：分片可存储到不同服务器
2. CDN集成：最终文件推送到CDN
3. 数据库持久化：元数据存入数据库而非文件
4. 清理任务：定期清理未完成的上传

总结与展望

通过这个完整的分片上传解决方案，我们实现了：

• ✅ 大文件稳定上传：告别网络波动导致的失败
• ✅ 断点续传：失败后从中断处继续，不浪费已上传内容
• ✅ 秒传功能：服务器已有文件时瞬间完成
• ✅ 进度精确显示：用户清晰了解上传状态
• ✅ 暂停恢复：用户完全控制上传过程
• ✅ 并发控制：既快速又不压垮浏览器

技术栈总结

• 前端：React + TypeScript + Web Worker
• 通信：自定义协议 + RESTful API
• 并发：Promise.all + 递归控制
• 存储：文件系统 + 元数据管理
• 优化：哈希计算 + 缓存策略

希望这篇详细的实践分享能帮助你在实际项目中解决大文件上传的痛点。如果你有任何问题或更好的建议，欢迎在评论区交流！

---

实战建议：先从小文件开始测试整个流程，逐步增加文件大小，确保每个环节都稳定可靠后再上线使用。