Node.js ZIP 处理库深度对比：adm-zip vs extract-zip vs node-unzip-2 vs unzipper

在 Node.js 开发中，处理 ZIP 文件是常见需求 —— 无论是解压用户上传的归档、动态生成部署包，还是集成第三方二进制工具。面对 adm-zip、extract-zip、node-unzip-2 和 unzipper 这四个主流选项，如何根据真实工程场景做出合理选型？本文从核心能力、内存模型、API 风格和适用边界出发，提供可落地的技术判断。

⚠️ 首要警告：关于 node-unzip-2 的状态

node-unzip-2 是原始 node-unzip 包的社区分支，而 node-unzip 早在多年前已被作者标记为 deprecated。尽管 node-unzip-2 在 npm 上仍可安装，但其 GitHub 仓库长期缺乏实质性更新，存在已知的内存泄漏和路径遍历漏洞（如未正确处理 .. 路径）。强烈建议新项目完全避开此包，已有项目应尽快迁移至 unzipper 或 extract-zip。

📦 核心功能定位：你是要“解压”还是“编辑”？

场景一：只需把整个 ZIP 解压到目录（如工具链集成）

如果你的任务类似于 “下载 ChromeDriver 并解压到 .local/bin”，那么你只需要一个 安全、可靠的解压器，无需读取或修改 ZIP 内容。

extract-zip 是此类场景的黄金标准。它专为此设计，内部使用 yauzl（一个只读、流式、注重安全的 ZIP 解析器），自动处理路径规范化，防止目录遍历攻击。

// extract-zip：简单安全的全量解压
const extract = require('extract-zip');

await extract('archive.zip', { dir: './output' });
// 所有文件被解压到 ./output，路径已安全校验

其他库也能实现类似功能，但需手动处理安全细节：

// adm-zip：需自行验证路径
const AdmZip = require('adm-zip');
const zip = new AdmZip('archive.zip');
zip.getEntries().forEach(entry => {
  if (!entry.isDirectory && !entry.entryName.includes('..')) {
    zip.extractEntryTo(entry, './output', false, true);
  }
});

// unzipper：需手动遍历并写入
const fs = require('fs');
const path = require('path');
const unzipper = require('unzipper');

await fs.createReadStream('archive.zip')
  .pipe(unzipper.Extract({ path: './output' }))
  .promise();

💡 结论：若只需“解压到目录”，无脑选 extract-zip —— 它少即是多。

场景二：需要读取或修改 ZIP 内容（如生成报告包）

如果你要动态向 ZIP 添加文件、读取特定条目内容，或在内存中构建 ZIP 后返回给客户端，则需要 完整的读写能力。

adm-zip 是唯一提供双向操作的库。它将整个 ZIP 加载到内存，允许增删改查，最后可写回文件或 Buffer。

// adm-zip：创建并修改 ZIP
const AdmZip = require('adm-zip');

const zip = new AdmZip();
zip.addFile('report.txt', Buffer.from('Hello World'));
zip.addLocalFile('./config.json');

// 读取现有条目
const entry = zip.getEntry('report.txt');
console.log(entry.getData().toString()); // 'Hello World'

// 写入磁盘
zip.writeZip('output.zip');

其他库均 不支持写入：

// extract-zip：只读，无 API 可写入
// node-unzip-2 / unzipper：仅支持解压，无法创建 ZIP

💡 结论：若需编辑 ZIP，adm-zip 是唯一选择，但要警惕大文件内存占用。

🌊 流式处理 vs 内存加载：大文件场景的关键分水岭

处理 100MB+ 的 ZIP 文件时，内存模型决定成败。

• adm-zip 将整个 ZIP 加载到内存。对于大文件，这可能导致 OOM（内存溢出）。
• extract-zip、unzipper 基于流式解析，内存占用恒定，适合大文件。
• node-unzip-2 虽声称流式，但实现有缺陷，易泄漏内存。

使用 unzipper 流式读取单个文件（低内存）

// unzipper：按需读取条目，内存友好
const unzipper = require('unzipper');

const directory = await unzipper.Open.file('large.zip');
const file = directory.files.find(f => f.path === 'data.csv');

if (file) {
  const content = await file.buffer(); // 仅加载该文件到内存
  console.log(content.toString());
}

使用 adm-zip 读取相同文件（高内存）

// adm-zip：整个 ZIP 被加载
const AdmZip = require('adm-zip');
const zip = new AdmZip('large.zip'); // 整个文件进内存！

const entry = zip.getEntry('data.csv');
const content = entry.getData(); // 已在内存中

💡 结论：大文件或内存敏感场景，优先 unzipper；小文件且需编辑，用 adm-zip。

🧪 API 风格：回调、Promise 还是 Async Iterator？

现代开发偏好 async/await 和流式接口。

• extract-zip：仅提供 Promise API，简单直接。
• unzipper：全面支持 Promise、Stream 和 Async Iterator（ES2018），适合现代流水线。
• adm-zip：同步 API 为主，部分方法有异步版本（如 writeZipPromise），但整体偏传统。
• node-unzip-2：仅支持回调（Callback），不符合现代规范。

使用 unzipper 的 for-await-of 遍历条目

// unzipper：现代异步迭代
const unzipper = require('unzipper');

for await (const entry of fs.createReadStream('archive.zip').pipe(unzipper.Parse())) {
  const fileName = entry.path;
  if (fileName.endsWith('.json')) {
    const content = await entry.buffer();
    processJSON(content);
  } else {
    entry.autodrain(); // 丢弃不需要的文件
  }
}

其他库无法如此优雅地实现按需处理：

// adm-zip：必须先加载全部
const zip = new AdmZip('archive.zip');
zip.getEntries().filter(e => e.entryName.endsWith('.json'))...

// extract-zip：无法访问单个条目

💡 结论：若需精细控制解压过程（如过滤、转换），unzipper 的流式 API 是最佳选择。

🔒 安全性：路径遍历防护

ZIP 文件可能包含恶意路径（如 ../../../etc/passwd），安全的库会自动规范化路径。

• extract-zip：内置防护，拒绝包含 .. 的路径。
• unzipper：通过 sanitize 选项默认启用路径清理。
• adm-zip：不自动防护，需开发者自行校验 entry.entryName。
• node-unzip-2：无有效防护，存在高危漏洞。

// unzipper：安全默认
fs.createReadStream('malicious.zip')
  .pipe(unzipper.Extract({ path: './safe' }))
  // 自动阻止 ../../../ 攻击

// adm-zip：需手动检查
zip.getEntries().forEach(entry => {
  if (entry.entryName.includes('..')) return; // 必须自己做
  zip.extractEntryTo(...);
});

💡 结论：处理不可信 ZIP 源时，优先选 extract-zip 或 unzipper。

📊 综合选型指南

💎 最终建议

• 90% 的解压需求：直接用 extract-zip —— 它解决了最常见、最危险的问题。
• 需要编辑 ZIP：用 adm-zip，但限制文件大小（<50MB），并手动校验路径。
• 处理大文件或构建管道：用 unzipper，发挥其流式优势。
• 永远不要在新项目中引入 node-unzip-2 —— 技术债不值得背。

记住：没有“最好”的库，只有“最合适”当前任务的工具。明确你的需求边界，就能避开大多数坑。