# fileUpload

**Repository Path**: fqcto/file-upload

## Basic Information

- **Project Name**: fileUpload
- **Description**: 大文件上传与断点续传 (Vue 3 + Node.js)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 大文件上传与断点续传 (Vue 3 + Node.js)

> 一个面向新手友好、可直接运行的「大文件上传 + 断点续传 + 秒传 + 并发分片」全栈案例。
>
> 前端:Vue 3 + Vite + spark-md5 + axios + Web Worker
> 后端:Node.js + Express + multer + fs-extra + cors + MySQL

---

## 🧰 技术简介(各自在本项目里干什么)

### 前端

| 技术 | 作用 |
|------|------|
| **Vue 3** | UI 框架。基于组合式 API (`<script setup>`) 写 [BigFileUploader.vue](web/src/components/BigFileUploader.vue),用 `ref` / `computed` 管理「文件、分片列表、上传状态、进度百分比」等响应式状态,并驱动按钮、进度条、分片网格的视图更新。本项目只有一个组件,所以**没有引入 Pinia**;状态足够轻,组件内 `ref` 就够了。 |
| **Vite** | 开发服务器 & 构建工具。提供秒开的热更新,并通过 [vite.config.js](web/vite.config.js) 把 `/api`、`/files` 代理到后端 `3000` 端口,前端调用接口时直接用相对路径,免去跨域配置。同时原生支持 `?worker` 后缀导入 Web Worker。 |
| **spark-md5** | 增量 MD5 计算库。对大文件分片后逐片 `append`,最后 `end()` 得到整文件指纹,作为**秒传判断**和**分片去重**的唯一 key(`fileHash` + `fileHash-index`)。 |
| **Web Worker** | 在独立线程里跑 spark-md5。[hash.worker.js](web/src/utils/hash.worker.js) 接收 `Blob[]`,边读边算,通过 `postMessage` 反馈进度,**避免大文件 hash 时主线程卡死**(UI 不会冻结)。 |
| **axios** | HTTP 客户端。[api/upload.js](web/src/api/upload.js) 里封装了 `verifyUpload` / `uploadChunk` / `mergeChunks` 三个接口;利用 axios 的 `onUploadProgress` 输出**每片实时上传进度**,并通过 `AbortController.signal` 在用户「暂停」时**取消进行中的请求**。 |

### 后端

| 技术 | 作用 |
|------|------|
| **Node.js** | 运行时。利用其异步 I/O 模型同时处理多分片并发上传与流式合并。 |
| **Express** | Web 框架。[app.js](server/app.js) 注册中间件与静态目录,[routes/upload.js](server/routes/upload.js) 提供三个核心接口:`POST /api/verify`(秒传校验 + 返回已上传分片清单)、`POST /api/upload`(接收分片)、`POST /api/merge`(合并分片)。 |
| **multer** | `multipart/form-data` 解析中间件。把前端上传的分片二进制以 `chunkHash` 为文件名,落到 `server/temp/<fileHash>/` 临时目录,**天然支持断点续传**——已经落盘的分片下次不会再传。 |
| **fs-extra** | Node `fs` 的增强版(自带 Promise + 递归创建/删除目录等)。[utils/file.js](server/utils/file.js) 用它做:① 检查最终文件是否已存在(秒传)、② 列出 `temp/<fileHash>` 下已落盘分片(断点续传清单)、③ 按 index 顺序**流式合并**所有分片到 `uploads/`、④ 合并完成后清理 temp 目录。 |
| **cors** | 跨域中间件。开发期前端 `5173` 直连后端 `3000` 时放行(虽然 Vite 也做了代理,这里多一层兜底,方便单独调试接口)。 |
| **mysql2** | MySQL 驱动(支持 Promise)。[utils/db.js](server/utils/db.js) 管理连接池与自动建库建表;上传完成后通过 `INSERT ... ON DUPLICATE KEY UPDATE` 将文件记录写入 `files` 表。 |
| **dotenv** | 环境变量管理。从 `.env` 文件读取 MySQL 连接参数,方便开发/生产切换。 |

---

## 📁 项目结构

```
fileUpload/
├── README.md                # 项目说明(本文件)
├── package.json             # 根目录脚本(一键启动前后端)
├── docs/                    # 📚 文档与新手教程
│   ├── 01-快速开始.md
│   ├── 02-原理详解.md
│   ├── 03-接口文档.md
│   └── 04-常见问题.md
│
├── server/                  # 🖥️ 后端服务 (Node + Express)
│   ├── package.json
│   ├── app.js               # 入口
│   ├── routes/upload.js     # 上传相关路由(verify/upload/merge)
│   ├── routes/files.js      # 文件清单管理(列表/编辑/删除)
│   ├── utils/file.js        # 文件合并/校验工具
│   ├── utils/db.js          # MySQL 连接池 & 初始化
│   ├── .env                 # 数据库等环境变量(不提交)
│   ├── .env.example         # 环境变量模板
│   ├── uploads/             # 已合并的最终文件 (运行后生成)
│   └── temp/                # 分片临时目录 (运行后生成)
│
└── web/                     # 🎨 前端项目 (Vue 3 + Vite)
    ├── package.json
    ├── vite.config.js
    ├── index.html
    └── src/
        ├── main.ts
        ├── App.vue
        ├── api/upload.ts              # 上传 axios 封装
        ├── api/files.ts               # 文件清单 axios 封装
        ├── utils/hash.js              # 计算 MD5 (Web Worker)
        ├── utils/hash.worker.js       # Worker 实现
        ├── utils/types.ts             # 共享类型定义
        ├── components/
        │   ├── BigFileUploader.vue    # ⭐ 核心上传组件
        │   ├── FileTable.vue          # 文件列表表格(分页/编辑/删除)
        │   └── Modal.vue              # 轻量弹窗组件
        └── styles/main.css
```

---

## 🚀 快速开始

### 1. 安装依赖

```bash
# 在项目根目录执行(会同时安装前后端依赖)
npm run setup
```

或者手动:

```bash
cd server && npm install
cd ../web && npm install
```

### 2. 配置 MySQL

```bash
# 复制环境变量模板
cd server
cp .env.example .env
```

编辑 `.env`,填入你的 MySQL 连接信息:

```ini
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=你的密码
MYSQL_DATABASE=file_upload
```

服务启动时会自动建库建表（`CREATE DATABASE IF NOT EXISTS` + `CREATE TABLE IF NOT EXISTS`），无需手动执行 SQL。

> **提示：** 如果当前环境没有 MySQL，服务仍然可以正常启动并处理上传 / 下载，只是文件清单页面无法拉取数据。

### 3. 启动项目

```bash
# 在项目根目录,一键启动前后端
npm run dev
```

启动后访问:

- 前端:http://localhost:5173
- 后端:http://localhost:3000

### 4. 试试上传

1. 选择一个大文件(建议 > 50MB,以便看到分片效果)。
2. 观察控制台打印的 hash 计算和分片上传过程。
3. 上传一半时点击「暂停」→ 刷新页面 → 选择同一文件 → 点击「恢复」,体验断点续传。
4. 上传完成后,再次选择同一文件,体验「秒传」。

---

## ✨ 实现的功能

| 功能 | 说明 |
|------|------|
| ✅ 大文件分片上传 | 默认每片 5MB,可在前端配置 |
| ✅ 秒传 | 通过文件 MD5 判断服务端是否已存在 |
| ✅ 断点续传 | 服务端返回已上传分片列表,前端跳过 |
| ✅ 暂停 / 恢复 | 取消未完成的请求,保留已完成的进度 |
| ✅ 并发上传 | 默认 4 个分片并发,提高吞吐 |
| ✅ Web Worker 计算 hash | 不阻塞主线程,大文件计算流畅 |
| ✅ 进度条 | 总进度 + 每个分片进度 |
| ✅ MySQL 持久化 | 上传完成自动录入 `files` 表 |
| ✅ 文件清单管理 | 分页表格展示、关键字搜索 |
| ✅ 编辑 / 删除 | 编辑文件名 & 备注;删除 DB + 物理文件 |
| ✅ 秒传补登记 | 秒传命中的文件也同步写入 MySQL |

---

## 📚 学习路线(推荐顺序)

1. [docs/01-快速开始.md](./docs/01-快速开始.md) — 5 分钟把项目跑起来
2. [docs/02-原理详解.md](./docs/02-原理详解.md) — 大文件上传到底是怎么工作的?
3. [docs/03-接口文档.md](./docs/03-接口文档.md) — 后端接口契约
4. [docs/04-常见问题.md](./docs/04-常见问题.md) — 踩坑与排查

---

## 🧪 浏览器要求

- 现代浏览器(Chrome / Edge / Firefox)
- 需要支持 `File API`、`Blob.slice`、`Web Worker`、`fetch / XMLHttpRequest`

---

## License

MIT