如何在Node.js中高效处理大文件上传与流式读写操作

在现代Web应用开发中，文件上传是一个非常常见的需求。然而，当用户尝试上传大文件（如视频、压缩包或日志文件）时，如果直接将整个文件加载到内存中进行处理，很容易导致服务器内存溢出（Out of Memory），进而引发服务崩溃。为了解决这个问题，Node.js 提供了强大的 Stream API，它允许我们以“分块”方式读取和写入数据，从而实现高效的流式处理。

本文将深入探讨如何利用 Node.js 的 fs.createReadStream 和 fs.createWriteStream 来构建一个健壮的大文件上传系统，并结合 Express 框架演示完整的实现流程。同时，我们会分析常见陷阱、性能瓶颈以及最佳实践，帮助你在生产环境中安全地处理任意大小的文件。

一、为什么不能直接读取大文件？

传统的文件读取方法如 fs.readFileSync 或 fs.readFile 是同步/异步一次性加载整个文件内容到内存中：

const data = fs.readFileSync('large-file.zip');
// 如果文件是 1GB，这会导致进程内存飙升！

这种做法的问题在于：

• 内存占用高，容易触发 GC 压力；
• 文件越大越不稳定，可能造成服务中断；
• 不适合高并发场景，因为每个请求都独占大量内存资源。

而 Stream 流式处理则完全不同：它将文件拆分成多个小块（chunk），按需读取并处理，极大降低内存压力。

二、核心原理：Node.js Stream API 简介

Node.js 中的 Stream 是一个抽象接口，分为四种类型：

我们重点使用的是 Readable 和 Writable 流来实现大文件上传的流式处理。

三、完整示例：基于 Express + Stream 的大文件上传

1. 安装依赖

npm install express multer

注意：虽然 multer 是流行的文件上传中间件，但它默认会把文件缓存在内存中，不适合超大文件。因此我们要手动接管流式处理逻辑。

2. 后端代码实现

const express = require('express');
const fs = require('fs');
const path = require('path');

const app = express();
const UPLOAD_DIR = './uploads';

if (!fs.existsSync(UPLOAD_DIR)) {
  fs.mkdirSync(UPLOAD_DIR);
}

app.use(express.json());

// 使用 raw body parser 避免 multer 默认行为
app.use((req, res, next) => {
  if (req.headers['content-type']?.includes('multipart/form-data')) {
    req.rawBody = '';
    req.on('data', chunk => req.rawBody += chunk);
    req.on('end', () => next());
  } else {
    next();
  }
});

app.post('/upload', (req, res) => {
  const filename = req.body.filename || 'unknown';
  const filepath = path.join(UPLOAD_DIR, filename);

  // 创建可写流
  const writeStream = fs.createWriteStream(filepath);

  // 监听错误事件
  writeStream.on('error', (err) => {
    console.error('写入失败:', err);
    res.status(500).json({ error: '文件写入失败' });
  });

  // 监听完成事件
  writeStream.on('finish', () => {
    console.log(`✅ 文件已成功保存: ${filepath}`);
    res.json({ message: '上传成功', file: filepath });
  });

  // 接收客户端发送的数据（这里是模拟的 raw body）
  // 实际上应该用 multer 的 diskStorage 或自定义 multipart 解析器
  const chunks = [];
  req.on('data', (chunk) => {
    chunks.push(chunk);
  });

  req.on('end', () => {
    const buffer = Buffer.concat(chunks);
    writeStream.write(buffer);
    writeStream.end(); // 关闭流
  });
});

⚠️ 上面的例子适用于简单场景，但不推荐用于真实项目中的多部分表单上传（Multipart）。更推荐的方式如下：

四、高级方案：使用 Multer 自定义存储策略 + Stream

Multer 支持自定义 storage，我们可以将其配置为流式写入磁盘：

const multer = require('multer');
const fs = require('fs');

const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, './uploads');
  },
  filename: function (req, file, cb) {
    cb(null, Date.now() + '-' + file.originalname);
  }
});

const upload = multer({ storage });

app.post('/upload-stream', upload.single('file'), (req, res) => {
  const { path } = req.file;
  res.json({ message: '上传完成', file: path });
});

不过，如果你希望完全控制流的生命周期（比如实时进度、校验、加密等），建议直接使用原始 HTTP 请求流。

五、进阶技巧：实时进度反馈与断点续传支持

1. 实时上传进度

可以通过监听 data 事件计算累计字节数：

let totalBytes = 0;
req.on('data', (chunk) => {
  totalBytes += chunk.length;
  console.log(`上传进度: ${totalBytes} bytes`);
});

前端可通过 WebSocket 或 SSE 实时更新进度条。

2. 断点续传（Resume Upload）

对于超过数小时的大文件上传，断点续传至关重要。你可以：

• 在数据库记录已上传的偏移量；
• 客户端发起请求时带上 Range 头；
• 后端根据偏移量跳过已上传部分继续写入。

示例：

const range = req.headers.range;
if (range) {
  const parts = range.replace(/bytes=/, "").split("-");
  const start = parseInt(parts[0], 10);
  const end = parts[1] ? parseInt(parts[1], 10) : undefined;

  const stat = fs.statSync(filepath);
  const fileSize = stat.size;
  const chunkSize = end ? end - start + 1 : fileSize - start;

  const readStream = fs.createReadStream(filepath, { start, end });
  res.writeHead(206, {
    'Content-Range': `bytes ${start}-${end || fileSize - 1}/${fileSize}`,
    'Accept-Ranges': 'bytes',
    'Content-Length': chunkSize,
  });
  readStream.pipe(res);
} else {
  // 正常上传逻辑
}

六、性能调优建议

七、总结

通过合理使用 Node.js 的 Stream API，我们可以轻松应对各种规模的文件上传任务，无论是几十 MB 还是几百 GB 的文件，都能做到稳定、高效、低内存消耗。关键在于：

• 不要一次性加载整个文件；
• 利用 createReadStream 和 createWriteStream 构建流链；
• 结合 Express 或 Koa 实现完整的上传管道；
• 加入断点续传、进度监控等增强功能。

这套方案已在多个大型项目中验证有效，特别适合云存储服务、视频转码平台、日志收集系统等需要长期运行且对稳定性要求高的场景。

如果你正在构建一个高性能文件上传服务，请务必优先考虑流式处理！这不仅是技术选择，更是架构成熟度的体现。

📌 延伸阅读

• Node.js Streams 文档
• Multer GitHub 示例
• Express File Upload Best Practices