Node.js 实战五：文件上传、下载、导出功能的实现与边界处理

最新推荐文章于 2025-12-27 10:49:59 发布

原创最新推荐文章于 2025-12-27 10:49:59 发布 · 860 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#node.js #前端

“你这能支持 Excel 导出吗？”

“上传文件能带进度条、断点续传吗？”

“导出的 ZIP 包打不开是为啥？”

别小看“文件上传下载”，这其实是前端与后端之间数据流动的桥梁系统，涉及：

HTTP 协议细节
编码格式转换
存储系统对接
安全性控制
前端兼容性挑战

本篇文章带你系统讲解 Node.js 中文件处理的完整方案：

上传 / 下载 / 导出 —— 你该怎么做、用什么工具、注意哪些坑。

一、文件上传的完整流程

浏览器端 → 后端处理 → 存储系统

常见文件上传方式：

类型	技术关键词	适合场景
表单上传	multipart/form-data	小文件上传，最通用
分片上传	Blob 切片 + 多次上传	大文件 / 秒传 / 断点续传
Base64 上传	将文件转为字符串	小图片 / 文本截图（不推荐大量使用）

二、使用 multer 处理上传文件（Express / Koa 通用）

安装依赖：

npm install multer

示例：

const multer = require('multer');
const upload = multer({ dest: 'uploads/' }); // 存到本地

router.post('/upload', upload.single('file'), async (req, res) => {
  const file = req.file;
  res.json({ filename: file.originalname, path: file.path });
});

多文件：

upload.array('files', 10) // 最多 10 个

注意事项：

fieldname 要与前端 <input name="file" /> 一致
支持自定义存储逻辑（比如上传至云 OSS）

三、断点续传 / 秒传原理（前后端配合实现）

基本思路：

文件切片 → 使用 File.slice() 将大文件拆成小片段
每片独立上传 + 记录状态（带 chunk index）
后端合并文件 fs.createWriteStream + pipe
利用 hash 实现“秒传”判断：文件是否已存在

推荐工具：前端可用 tus、plupload；后端可结合 Redis 存续传状态

四、文件下载的几种形式

原始文件下载（流方式）：

router.get('/download/:filename', async (ctx) => {
  const path = `./uploads/${ctx.params.filename}`;
  ctx.set('Content-disposition', `attachment; filename=${ctx.params.filename}`);
  ctx.body = fs.createReadStream(path);
});

动态文件生成并下载（如 Excel、PDF）

可使用：

Excel：exceljs, xlsx
PDF：pdfkit, puppeteer (html to pdf)
CSV：手动拼接或使用 fast-csv

五、导出为 ZIP 包

使用 archiver 打包多个文件：

const archiver = require('archiver');
router.get('/zip', async (ctx) => {
  ctx.set('Content-type', 'application/zip');
  ctx.set('Content-disposition', 'attachment; filename=all.zip');

  const archive = archiver('zip');
  archive.pipe(ctx.res);

  archive.file('uploads/a.txt', { name: 'a.txt' });
  archive.file('uploads/b.txt', { name: 'b.txt' });

  await archive.finalize();
  ctx.respond = false;
});

Node.js 流式输出不要忘记设置 ctx.respond = false

六、安全性与兼容性注意事项

问题	解决方案
上传限制	校验 MIME 类型、文件大小、黑名单（.exe）
覆盖问题	用 uuid 命名文件，或限制上传路径
跨域问题	确保 CORS 设置允许上传域名、携带 Cookie
下载出错	Content-Type、Content-Disposition 必须正确设置
中文文件名乱码	使用 encodeURIComponent 处理 header 中文名