如何用 adm-zip 轻松搞定 Node.js 中的 ZIP 文件操作？超实用教程

如何用 adm-zip 轻松搞定 Node.js 中的 ZIP 文件操作？超实用教程 🚀

【免费下载链接】adm-zip A Javascript implementation of zip for nodejs. Allows user to create or extract zip files both in memory or to/from disk 项目地址: https://gitcode.com/gh_mirrors/ad/adm-zip

adm-zip 是一个纯 JavaScript 编写的 ZIP 文件处理库，专为 Node.js 环境设计。它让开发者能够轻松创建、读取、修改 ZIP 文件，支持内存操作和磁盘读写，无需依赖任何外部二进制工具。无论你是需要解压用户上传的压缩包，还是生成动态内容的 ZIP 下载，adm-zip 都能提供高效可靠的解决方案。

📦 快速上手：5 分钟安装指南

一行命令完成安装

通过 npm 安装 adm-zip 只需简单一步：

npm install adm-zip

安装完成后，即可在项目中通过 require('adm-zip') 引入使用。

🚀 核心功能全解析

1. 读取 ZIP 文件（基础操作）

创建 AdmZip 实例并加载 ZIP 文件，即可获取所有条目信息：

const AdmZip = require('adm-zip');
const zip = new AdmZip('./test/assets/normal.zip'); // 加载测试文件
const entries = zip.getEntries(); // 获取所有文件条目

entries.forEach(entry => {
  console.log(`文件名: ${entry.entryName}, 大小: ${entry.uncompressedSize} bytes`);
});

测试文件路径参考：test/assets/normal.zip

2. 解压文件到磁盘 ⚡

支持单文件解压或全量解压，灵活控制路径和覆盖策略：

// 解压单个文件
zip.extractEntryTo('some_file.txt', './output', false, true);

// 解压全部内容
zip.extractAllTo('./all_files', true); // 第二个参数为是否覆盖现有文件

3. 创建自定义 ZIP 包 📁

从零开始构建 ZIP 文件，支持内存数据和本地文件：

const zip = new AdmZip();

// 添加内存中的文本内容
zip.addFile('hello.txt', Buffer.from('Hello World!'), '这是一个示例文件');

// 添加本地图片
zip.addLocalFile('./images/logo.png');

// 保存到磁盘
zip.writeZip('./my_archive.zip');

🔒 高级功能：加密与特殊场景处理

密码保护文件读取

对于加密的 ZIP 文件，在获取条目时传入密码即可解密：

const encryptedZip = new AdmZip('./test/assets/issue-471-infozip-encrypted.zip');
const entries = encryptedZip.getEntries('secret_password'); // 传入密码参数

加密测试用例：test/issue_471/infozip-password.test.js

大文件与目录处理

adm-zip 支持超大目录压缩，自动处理深层嵌套结构：

// 测试用例参考：处理超过 4GB 的目录
const largeZip = new AdmZip('./test/assets/large_directory_size.zip');
largeZip.extractAllTo('./large_output');

大文件测试模块：test/large_directory_size/

🛠️ 项目结构与核心模块

adm-zip 采用模块化设计，核心逻辑清晰分离：

adm-zip/
├── adm-zip.js          # 主入口，提供 ZIP 操作 API
├── zipFile.js          # ZIP 文件解析与生成
├── zipEntry.js         # 单个 ZIP 条目处理
├── methods/            # 压缩算法实现（deflate/inflate/zipcrypto）
├── headers/            # ZIP 头信息解析（mainHeader/entryHeader）
└── util/               # 工具函数（常量/错误处理/解码器）

核心算法模块路径：methods/ | 工具函数：util/utils.js

💡 实用技巧与最佳实践

1. 内存中处理 ZIP
   使用 toBuffer() 方法直接获取 ZIP 内容的 Buffer，适用于 HTTP 响应：

   const zipBuffer = zip.toBuffer();
   res.setHeader('Content-Type', 'application/zip');
   res.end(zipBuffer);
   

2. 编码问题解决
   处理中文等多字节文件名时，确保使用正确的解码器：

   // 多字节测试用例：[test/mbcs/mbcs.test.js](https://link.gitcode.com/i/666fa3d9d3323ecb5d1edbd35da80d6f)
   

3. Electron 环境适配
   在 Electron 中使用 original-fs 模块提升性能：

   const zip = new AdmZip('./file.zip', { fs: require('original-fs') });
   

📚 学习资源与贡献指南

• 官方文档：完整 API 说明与更多示例
• 测试用例：test/ 目录包含 20+ 场景的可运行示例
• 贡献代码：通过 GitHub PR 提交改进，核心功能开发可参考 util/constants.js 中的常量定义

adm-zip 作为轻量级 ZIP 处理库，平衡了性能与易用性，已成为 Node.js 生态中处理压缩文件的首选工具之一。无论是简单的解压需求还是复杂的 ZIP 生成场景，它都能提供稳定可靠的支持。现在就通过 npm install adm-zip 体验高效的 ZIP 文件操作吧！

【免费下载链接】adm-zip A Javascript implementation of zip for nodejs. Allows user to create or extract zip files both in memory or to/from disk 项目地址: https://gitcode.com/gh_mirrors/ad/adm-zip