你是不是也遇到过，上传个几百M的安装包或者设计稿，眼瞅着进度条走到99%，然后……网络波动一下，啪，没了！又要从头再来？相信我，这种崩溃的感觉我太懂了。

最近刚好在弄文件上传的小工具，又把这块硬骨头啃了一遍。今天不聊虚的，就把我这次用 FastAPI 和 Vue 实现大文件分片上传的完整思路，还有踩过的坑，都倒出来给你听。

🎯 核心摘要：读完你能带走什么？

这篇文章不会给你扔一堆晦涩的概念就跑。我会用讲故事的方式，跟你讲明白：

👉 分片上传到底是怎么一回事儿，原理是啥。

👉 秒传和断点续传的核心逻辑（其实就隔一层窗户纸）。

👉 一份可以直接复制粘贴拿去用的 FastAPI 后端核心代码。

👉 一份 Vue3 前端的实现思路和关键代码片段。

🗺️ 主要内容脉络

1️⃣ 从一次抓狂的上传失败说起

2️⃣ 别再盯着进度条了：聊聊分片、哈希与秒传

3️⃣ 后端实战：FastAPI如何像收快递一样收文件

4️⃣ 前端实战：Vue里那把切文件的“菜刀”

5️⃣ 跑起来！以及那些年我踩过的坑

6️⃣ 结尾碎碎念

1️⃣ 从一次抓狂的上传失败说起

手机上传一段视频到电脑，“每次到一半就挂” 我一看日志， 413 Request Entity Too Large ，Nginx和FastAPI双双拦截。

调整配置大小限制？那是治标不治本，大文件上传慢、易失败是HTTP协议天生的短板。

这就是为啥我们需要 分片上传。

思路特简单：把大象放进冰箱要几步？不对，是把大文件切成小块，一块块传，最后在服务端拼起来。

2️⃣ 别再盯着进度条了：聊聊分片、哈希与秒传

好，咱们先来理顺几个核心概念，别急着写代码。

🔹 文件切片（Blob.slice）

浏览器里，我们可以用 file.slice() 方法，像切西瓜一样把一个 File 对象切成一个个 Blob 。比如设定每片5MB，一个100MB的文件就变成了20个小块。

🔹 文件哈希（Spark-MD5）

接下来重点来了！文件指纹，也就是MD5值。 这玩意儿是文件的唯一身份证号。你可能会问，为啥要算这个？

一是为了 秒传：后端一看，“哟，这个MD5我数据库里有啊，文件存着呢！” 直接告诉你“传完了”，用户体验瞬间起飞。
二是为了 校验：确保服务端拼起来的文件没缺胳膊少腿。

这里千万别学我当初偷懒，想着用 文件名+修改时间 来当唯一标识，结果用户把文件重命名一下，或者换个文件夹上传，后端就傻傻地又存了一份一模一样的垃圾数据。

🔹 断点续传

原理就是每次上传前，先拿MD5去问后端：“我这文件，哪些片你已经有了？”
后端返回一个数组，比如 [0, 1, 3] ，意思就是第0、1、3片传过了。前端直接跳过这些片，从第2片开始传。

是不是以为这样就完了？对，核心就这么简单！

3️⃣ 后端实战：FastAPI如何像收快递一样收文件

咱们后端用的是 Python 界的当红炸子鸡 FastAPI，它处理文件上传异步非阻塞，性能杠杠的。

📍 检查分片接口（实现秒传+断点续传）

@app.post("/upload/check")
async def check_chunks(file_hash: str, total_chunks: int):
    # 1. 去数据库查这个hash
    file_record = await db.get_file_by_hash(file_hash)
    if file_record:
        # 如果存在完整文件记录，直接返回秒传信号
        return {"status": "success", "code": 200, "data": {"uploaded": True}}
    
    # 2. 不存在，就去磁盘找临时分片文件夹
    temp_dir = Path(f"temp/{file_hash}")
    uploaded_chunks = []
    if temp_dir.exists():
        for chunk_file in temp_dir.iterdir():
            # 文件名约定为 chunk_index
            uploaded_chunks.append(int(chunk_file.stem))
    
    return {"status": "success", "data": {"uploaded": False, "uploaded_chunks": uploaded_chunks}}

再说个容易翻车的点： 临时文件夹的路径设计。
千万别把所有分片都扔一个文件夹里，文件多了系统查找速度会变慢。按 file_hash 的前两位或者直接建一个同名文件夹，是最稳妥的做法。

📍 上传分片接口

@app.post("/upload/chunk")
async def upload_chunk(
    file: UploadFile = File(...),
    file_hash: str = Form(...),
    chunk_index: int = Form(...),
):
    temp_dir = Path(f"temp/{file_hash}")
    temp_dir.mkdir(exist_ok=True)
    
    chunk_path = temp_dir / str(chunk_index)
    # 把上传的分片内容异步写入磁盘
    with open(chunk_path, "wb") as f:
        while content := await file.read(1024 * 1024): # 1MB一读
            f.write(content)
            
    return {"status": "success", "chunk_index": chunk_index}

📍 合并分片接口

@app.post("/upload/merge")
async def merge_chunks(file_hash: str, file_name: str, total_chunks: int):
    temp_dir = Path(f"temp/{file_hash}")
    target_path = Path(f"uploads/{file_hash}_{file_name}")
    
    # 注意：要按照分片索引顺序写入！
    with open(target_path, "wb") as target_f:
        for i in range(total_chunks):
            chunk_path = temp_dir / str(i)
            with open(chunk_path, "rb") as chunk_f:
                target_f.write(chunk_f.read())
    
    # 清理临时分片和文件夹（这里可以用 shutil.rmtree）
    # 校验MD5是否一致...
    # 写入数据库记录...
    
    return {"status": "success", "code": 200}

4️⃣ 前端实战：Vue里那把切文件的“菜刀”

前端我用的是 Vue3 + Element Plus ，核心库是 spark-md5 。

🔪 第一步：切肉，不对，切文件并计算Hash

计算大文件的MD5是个CPU密集型任务，如果直接卡在主线程，页面会直接假死。
官方文档虽然建议用 Worker，但根据以往的经验，不用 Worker 而是用 requestIdleCallback 或者分片读取计算，对小几G的文件来说，体验也是OK的，代码还少。

// 伪代码示例，思路最重要
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB一片

async function handleUpload(file) {
  const chunks = createChunks(file);
  // 计算Hash (这里略去具体SparkMD5的增量计算代码，否则太长了)
  const fileHash = await computeHash(chunks);
  
  // 1. 检查是否秒传或需要断点续传
  const { uploaded, uploadedChunks } = await checkChunksApi(fileHash, chunks.length);
  
  if (uploaded) {
    ElMessage.success('文件秒传成功！');
    return;
  }
  
  // 2. 过滤出未上传的分片
  const pendingChunks = chunks.filter((_, index) => !uploadedChunks.includes(index));
  
  // 3. 并发上传 (千万别同时全发出去，要控制并发数，比如一次最多6个)
  await uploadChunksWithPool(pendingChunks, fileHash, 6);
  
  // 4. 通知后端合并
  await mergeChunksApi(fileHash, file.name, chunks.length);
  ElMessage.success('总算传完了，合并成功！');
}

这个工具的选择，好比选螺丝刀，不是最贵的最好，而是最顺手的。这里用 spark-md5 完全够用，别为了高大上去引入一整套 crypto-js，太重了。

5️⃣ 跑起来！以及那些年我踩过的坑

⚠️ 坑一：分片大小怎么定？

别设太小，比如100KB，那样请求数爆炸，浏览器并发扛不住，后端压力也大。也别太大，失去断点续传的意义。个人经验， 5MB 或 10MB 是个很舒服的区间。

⚠️ 坑二：合并文件时的顺序！

后端合并分片时，千万注意要按照 chunk_index 从小到大写入。如果你用了 os.listdir() 然后直接遍历，系统返回的顺序可能是乱的，拼出来的文件就坏了。我就这么坏过一个3个G的模型包，血泪教训啊！

⚠️ 坑三：并发上传控制

浏览器对同一域名的并发连接数是有限制的（HTTP/1.1一般是6个）。如果你 for 循环里直接发几百个请求，后面的请求全得排队，甚至直接失败。一定要写个简单的请求池，控制同时在传的分片数。

💡 结尾碎碎念

大文件上传这玩意儿，看着唬人，其实拆解开来就三件事：切、传、合。核心难点都在异常处理和细节的打磨上。希望我今天掏心窝子的这些分享，能让你在实现这个功能时，少熬几个大夜，少掉几根头发。

如果你在实际操作中遇到了什么妖魔鬼怪的问题，或者有更好的实现思路，欢迎随时留言找我唠嗑。技术在交流中才会变得更有趣嘛。

👩‍💻 原创不易，如果觉得这篇文章对你有用，别忘了点个「赞」和「关注」，再顺手「分享」给那个同样被大文件上传折磨的难兄难弟吧~ 这样我才更有动力去踩下一个坑，然后回来写给你们看呀！😉