Node.js如何以最少依赖将Buffer解压到目录？解决unzipper兼容问题

问题背景 #

我通过GET请求从API获取到一个包含目录/文件结构的Buffer，想要解压到指定文件夹里。之前用unzipper库一直正常，但在Node.js v19.8.0和v19.8.1里失效了——解压完的文件全是损坏的，而且unzipper依赖多，部分依赖在新版本Node.js里兼容性有问题。当前代码如下：

function unzipBufferToFolder(data, folder, callback)
{
    unzip.Open.buffer(data)
        .then(d => d.extract({path: folder}), reportError)
        .then(callback, reportError)
}

低依赖解决方案 #

优先推荐用轻量、维护活跃的zip处理库，以下是两种可行方案：

方案一：使用yauzl（轻量zip解析库，依赖极少） #

yauzl是专注于zip文件解析的库，没有冗余依赖，对新版本Node.js兼容性好，支持直接从Buffer读取zip内容。

1. 安装依赖：

npm install yauzl

2. 实现代码：

const yauzl = require('yauzl');
const fs = require('fs').promises;
const path = require('path');

async function unzipBufferToFolder(buffer, targetFolder) {
    // 确保目标文件夹存在，不存在则创建
    await fs.mkdir(targetFolder, { recursive: true });

    return new Promise((resolve, reject) => {
        // 从Buffer打开zip文件，启用lazyEntries避免一次性加载所有内容
        yauzl.fromBuffer(buffer, { lazyEntries: true }, (err, zipfile) => {
            if (err) return reject(err);

            zipfile.readEntry();
            // 处理每个zip条目（文件/目录）
            zipfile.on('entry', async (entry) => {
                // 判断是否为目录（文件名以/结尾）
                if (/\/$/.test(entry.fileName)) {
                    const dirPath = path.join(targetFolder, entry.fileName);
                    await fs.mkdir(dirPath, { recursive: true });
                    zipfile.readEntry();
                } else {
                    // 处理文件，打开读取流
                    zipfile.openReadStream(entry, async (err, readStream) => {
                        if (err) return reject(err);

                        const filePath = path.join(targetFolder, entry.fileName);
                        // 确保文件所在的父目录存在
                        await fs.mkdir(path.dirname(filePath), { recursive: true });
                        
                        // 创建写入流，将文件内容写入目标路径
                        const writeStream = fs.createWriteStream(filePath);
                        readStream.pipe(writeStream);
                        
                        // 写入完成后继续处理下一个条目
                        writeStream.on('finish', () => zipfile.readEntry());
                        writeStream.on('error', reject);
                    });
                }
            });

            // 所有条目处理完成
            zipfile.on('end', resolve);
            zipfile.on('error', reject);
        });
    });
}

// 使用示例
// const apiBuffer = ... // 从API获取的zip Buffer
// unzipBufferToFolder(apiBuffer, './my-target-folder')
//     .then(() => console.log('解压成功'))
//     .catch(err => console.error('解压失败:', err));

方案二：使用extract-zip（上层封装API，更简洁） #

extract-zip基于yauzl封装，提供了更简洁的解压API，同样依赖极少，适合快速实现。

1. 安装依赖：

npm install extract-zip

2. 实现代码：

const extract = require('extract-zip');
const fs = require('fs').promises;
const path = require('path');
const os = require('os');

async function unzipBufferToFolder(buffer, targetFolder) {
    // 确保目标文件夹存在
    await fs.mkdir(targetFolder, { recursive: true });
    
    // 先将Buffer写入临时文件（extract-zip暂不支持直接传入Buffer）
    const tempZipPath = path.join(os.tmpdir(), `temp-zip-${Date.now()}.zip`);
    await fs.writeFile(tempZipPath, buffer);

    try {
        // 执行解压
        await extract(tempZipPath, { dir: targetFolder });
    } finally {
        // 无论成功失败，都删除临时文件
        await fs.unlink(tempZipPath);
    }
}

// 使用示例
// unzipBufferToFolder(apiBuffer, './my-target-folder')
//     .then(() => console.log('解压成功'))
//     .catch(err => console.error('解压失败:', err));

为什么unzipper失效？ #

unzipper依赖的fstream等模块在Node.js新版本中已被标记为废弃，且部分底层逻辑未适配Node.js v19的API变更，导致解压过程中出现静默错误，最终生成损坏的文件。而yauzl这类库采用更现代的实现，避免了这些兼容性问题。

内容的提问来源于stack exchange，提问作者Miroslav Popov