Node.js 使用 adm-zip 操作 ZIP 文件指南

1. 安装依赖

在项目中安装 adm-zip 包：

bash
npm install adm-zip

2. 初始化对象

引入模块后，根据需求选择不同的初始化方式：

typescript
var AdmZip = require('adm-zip')

// 读取现有 ZIP 文件
var zip = new AdmZip('./my_file.zip')

// 创建新的 ZIP 对象（用于生成新压缩包）
var zipCreating = new AdmZip()

• new AdmZip(path): 加载现有文件。
• new AdmZip(): 创建空对象用于后续添加文件。

3. 核心功能 API

3.1 遍历文件列表

使用 getEntries 获取压缩包内所有条目，并通过 forEach 遍历。

typescript
var zipEntries = zip.getEntries()

zipEntries.forEach(function (zipEntry) {
  console.log(zipEntry.toString())
  if (zipEntry.entryName == 'my_file.txt') {
    console.log(zipEntry.getData().toString('utf8'))
  }
})

• getEntries(): 返回包含所有条目的数组。
• zipEntry.entryName: 获取文件在压缩包内的路径。
• zipEntry.isDirectory: 判断是否为目录。
• zipEntry.getData(): 获取文件内容的 Buffer 数据。

3.2 读取文件内容

直接读取指定文件的文本内容。

typescript
console.log(zip.readAsText('my_file.txt'))

• readAsText(entryName): 将指定条目内容作为字符串返回。

3.3 提取单个文件

将压缩包内的特定文件提取到指定目录。

typescript
zip.extractEntryTo(
  'my_file.txt',   // 条目名称
  './src',         // 目标路径
  false,           // maintainEntryPath: 是否保持条目路径结构
  true             // overwrite: 是否覆盖现有文件
)

maintainEntryPath 参数详解

值	说明	示例
true	保持压缩包内的完整路径结构	config/settings.json → ./src/config/settings.json
false	只提取文件，不保留目录结构	config/settings.json → ./src/settings.json

场景对比：

假设 ZIP 内有 config/settings.json 文件：

typescript
// 不保持路径
zip.extractEntryTo('config/settings.json', './src', false, true)
// 结果：./src/settings.json

// 保持路径
zip.extractEntryTo('config/settings.json', './src', true, true)
// 结果：./src/config/settings.json

选择建议：

场景	推荐值
只想提取单个文件，不关心目录	false
需要保持项目原有结构	true
批量解压多个相关文件	true
扁平化输出所有文件	false

3.4 解压所有文件

将整个压缩包内容一次性解压到指定目录。

typescript
zip.extractAllTo('./src', true)

• extractAllTo(targetPath, overwrite): 批量解压操作。

3.5 创建并写入 ZIP 文件

向 AdmZip 实例添加文件内容，并保存为新的 .zip 文件。

typescript
var content = 'inner content of the file'
// 添加文件：文件名，内容 Buffer，注释
zip.addFile('test.txt', Buffer.from(content, 'utf8'), 'entry comment goes here')
// 写入磁盘
zip.writeZip('./test.zip')

• addFile(name, content, comment): 向压缩包添加新条目。
• Buffer.from(): 将字符串转换为 Buffer 流。
• writeZip(path): 将内存中的 ZIP 对象保存为物理文件。

4. 方法参数速查表

方法	参数 1	参数 2	参数 3	参数 4
extractEntryTo	entryName	targetPath	maintainEntryPath	overwrite
extractAllTo	targetPath	overwrite	-	-
addFile	name	content	comment	-

5. 注意事项

• 路径存在性: 确保解压或写入的目标目录存在，否则可能报错。
• 字符编码 : 处理中文文件名或内容时，注意指定编码（如 utf8）。
• 密码支持 : 代码中定义了 password 变量，若需加密压缩包，需查阅 adm-zip 关于密码保护的具体 API 支持。