Node.js 中 ZIP 文件处理库深度对比：adm-zip、extract-zip、node-unzip-2、node-zip、unzipper 与 yauzl

在 Node.js 开发中，处理 ZIP 文件是常见需求 —— 无论是解压用户上传的归档、生成下载包，还是解析依赖资源。但面对 adm-zip、extract-zip、node-unzip-2、node-zip、unzipper 和 yauzl 这些库，开发者常陷入选择困境。它们功能重叠却各有侧重，有的擅长写入，有的专注读取；有的简单直接，有的支持流式处理。本文从真实工程场景出发，深入比较这些库的核心能力、API 设计与适用边界。

📦 功能定位：谁做解压？谁做压缩？

首先明确一点：并非所有库都同时支持压缩与解压。这是选型的第一道分水岭。

支持完整读写（压缩 + 解压）

• adm-zip：提供完整的 ZIP 文件创建、修改和提取能力。
• node-zip：基于 JSZip 封装，支持内存中的 ZIP 构建与解析。
• unzipper：虽以“解压”命名，但其实也支持 ZIP 写入（通过 ZipWriter）。

仅支持解压（只读）

• extract-zip：专为将 ZIP 文件解压到磁盘目录而设计，不支持内存操作或压缩。
• yauzl：纯只读库，专注于高效、低内存地读取 ZIP 内容，不提供任何写入 API。
• node-unzip-2：仅支持解压，且主要面向流式处理 ZIP 条目。

⚠️ 注意：node-unzip-2 是 node-unzip 的社区维护分支，原项目已不再活跃。虽然它仍可工作，但在新项目中建议优先评估更现代的替代品。

💾 解压到磁盘：简单任务 vs 精细控制

最常见的需求是“把 ZIP 文件解压到某个文件夹”。此时，extract-zip 是最直接的选择。

// extract-zip: 一行代码解压到目录
const extract = require('extract-zip');

await extract('archive.zip', { dir: './output' });

相比之下，其他库需要更多代码：

// adm-zip: 需要显式调用 extractAllTo
const AdmZip = require('adm-zip');
const zip = new AdmZip('archive.zip');
zip.extractAllTo('./output');

// unzipper: 需要 pipe 到目录流
const unzipper = require('unzipper');
await fs.createReadStream('archive.zip')
  .pipe(unzipper.Extract({ path: './output' }))
  .promise();

// yauzl: 必须手动遍历条目并写入文件
const yauzl = require('yauzl');
yauzl.open('archive.zip', (err, zipfile) => {
  zipfile.on('entry', (entry) => {
    // 手动处理每个 entry，创建目录、写入文件等
  });
});

结论：如果只是简单解压到磁盘，extract-zip 最省事。若需精细控制（如过滤文件、转换内容），则需 unzipper 或 yauzl。

🧠 内存操作：构建 ZIP 或解析内容

当需要在内存中动态生成 ZIP（如打包多个 Buffer）或解析 ZIP 内容而不写入磁盘时，adm-zip 和 node-zip 更合适。

// adm-zip: 添加 Buffer 并获取最终 Buffer
const zip = new AdmZip();
zip.addFile('file.txt', Buffer.from('Hello'));
const buffer = zip.toBuffer();

// node-zip: 基于 JSZip，链式 API
const Zip = require('node-zip');
const zip = new Zip();
zip.file('file.txt', 'Hello');
const buffer = zip.generate({ type: 'nodebuffer' });

而 unzipper 也能读取内存中的 ZIP：

// unzipper: 从 Buffer 解析
const directory = await unzipper.Open.buffer(buffer);
const fileContents = await directory.files[0].buffer();

yauzl 同样支持 Buffer 输入，但需自行管理流：

// yauzl: 从 Buffer 读取
yauzl.fromBuffer(buffer, (err, zipfile) => {
  zipfile.on('entry', (entry) => {
    zipfile.openReadStream(entry, (err, readStream) => {
      // 处理流
    });
  });
});

🌊 流式处理：大文件与低内存场景

处理大型 ZIP 文件时，内存占用是关键。yauzl 和 unzipper 原生支持流式读取，避免一次性加载整个文件。

// yauzl: 流式读取（推荐用于大文件）
const yauzl = require('yauzl');
yauzl.open('large.zip', (err, zipfile) => {
  zipfile.on('entry', (entry) => {
    zipfile.openReadStream(entry, (err, readStream) => {
      readStream.pipe(process.stdout); // 或写入文件
    });
  });
});

// unzipper: 同样支持流
fs.createReadStream('large.zip')
  .pipe(unzipper.Parse())
  .on('entry', (entry) => {
    entry.pipe(process.stdout);
  });

而 adm-zip 和 node-zip 默认将整个 ZIP 加载到内存，不适合大文件：

// adm-zip: 整个文件加载到内存
const zip = new AdmZip('large.zip'); // 可能 OOM

结论：处理 >100MB 的 ZIP 文件时，优先选择 yauzl 或 unzipper。

🔒 安全性与可靠性

ZIP 文件可能包含路径遍历攻击（如 ../../../etc/passwd）。安全的库会自动规范化路径。

• extract-zip：内置路径校验，防止目录遍历。
• unzipper：Extract 模式默认启用 forceStream: true 和路径检查。
• yauzl：不处理路径安全，需开发者自行验证 entry.fileName。
• adm-zip：extractAllTo() 方法有 overwrite 和 keepOriginalPermission 选项，但路径安全需谨慎处理。

// extract-zip: 自动防御路径遍历
await extract('malicious.zip', { dir: './safe' }); // 即使 ZIP 内含 ../ 也会被限制在 ./safe

因此，在处理不可信来源的 ZIP 时，extract-zip 和 unzipper 更安全。

🛠️ API 设计与易用性

• adm-zip：面向对象，API 直观，适合快速原型开发。
• extract-zip：单一用途，API 极简。
• node-zip：封装 JSZip，熟悉前端 JSZip 的开发者上手快。
• unzipper：支持 Promise、流、事件，灵活但略复杂。
• yauzl：底层、回调风格，学习曲线陡峭，但控制力最强。
• node-unzip-2：流式 API，但文档较少，社区支持弱。

📌 总结：如何选择？

💡 最终建议

• 新项目首选 unzipper：它平衡了功能、安全性和现代 API（Promise/流），既能解压到磁盘，也能处理内存和流式场景。
• 仅解压到磁盘？用 extract-zip：简单任务不必过度设计。
• 需要写入 ZIP？选 adm-zip：成熟稳定，API 清晰。
• 极致性能与控制？用 yauzl：但准备好写更多胶水代码。

记住：没有“最好”的库，只有“最合适”当前场景的工具。理解每个库的设计边界，才能在工程中做出稳健选择。