asai-nodejs-zip — ZIP 压缩/解压缩插件

功能概述

asai-nodejs-zip 基于 compressing 库，提供 ZIP 格式的文件夹压缩、文件压缩、解压缩和流式压缩功能。所有方法均返回 Promise。

入口文件 — zip.js

依赖

import compressing from 'compressing';
import fs from 'fs';

API 详细说明

zip(zipf, dir, opts)

压缩文件夹为 ZIP 文件。

参数： | 参数 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | zipf | string | ✓ | — | 目标 ZIP 文件路径 | | dir | string | ✓ | — | 要压缩的源文件夹路径 | | opts | object | ✗ | {} | 配置选项 |

opts 选项： | 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | ignoreBase | boolean | false | 为 true 时，压缩忽略源文件夹根目录，仅打包内部文件和子文件夹 | | zipFileNameEncoding | string | 'utf8' | 文件名编码（支持 gbk、shift_jis 等） |

编码支持： | 语言 | 编码值 | |------|--------| | 简体中文 | gbk, gb18030, gb2312, cp936 | | 繁体中文 | big5, cp950 | | 韩文 | cp949, euc-kr | | 日文 | sjis(shift_jis), cp932, euc-jp |

示例：

const zip = require('./zip');

// 压缩文件夹
await zip.zip('./output.zip', './data', { ignoreBase: true });

// 压缩文件夹（中文编码）
await zip.zip('./中文文件.zip', './data', { zipFileNameEncoding: 'gbk' });

zipfile(zipf, file, opts)

压缩单个文件为 ZIP 文件。

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | zipf | string | ✓ | 目标 ZIP 文件路径 | | file | string | ✓ | 要压缩的源文件路径 | | opts | object | ✗ | 配置选项（同 zip()） |

示例：

// 压缩单个文件
await zip.zipfile('./myfile.zip', './document.docx');

unzip(zipf, dir, opts)

解压缩 ZIP 文件到指定目录。

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | zipf | string | ✓ | 要解压的 ZIP 文件路径 | | dir | string | ✓ | 解压目标目录 | | opts | object | ✗ | 配置选项（同 zip()） |

示例：

// 解压缩
await zip.unzip('./backup.zip', './restore/');

zipstream(zipf, dir)

使用流式方式压缩文件夹。

与 zip() 的区别：

• zipstream() 逐个文件添加，对大文件夹更节省内存
• 当前实现仅压缩直接子文件（不含子目录递归）

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | zipf | string | ✓ | 目标 ZIP 文件路径 | | dir | string | ✓ | 源文件夹路径 |

示例：

// 流式压缩
await zip.zipstream('./data.zip', './upload/');

使用示例

const zip = require('./zip');

async function backupAndRestore() {
    // 1. 压缩项目文件夹（忽略根目录）
    await zip.zip(
        './backups/project-2024.zip',
        './my-project/',
        { ignoreBase: true }
    );

    // 2. 解压到新位置
    await zip.unzip(
        './backups/project-2024.zip',
        './restored-project/'
    );
}

注意事项

1. 依赖 compressing 包，请确保已安装
2. 处理中文文件名时，建议指定 zipFileNameEncoding: 'gbk'
3. zipstream() 当前版本仅处理直接子文件，不递归子目录
4. 所有方法均为异步，返回 Promise

代码分析与优化建议

✅ 已优化项目

1. zipstream() 支持递归子目录 ✅

优化内容：改用递归遍历 walkDir() 支持子目录，功能与 zip() 完全对齐。

// 新增 walkDir 辅助函数，递归遍历所有文件
function walkDir(dir) {
    const entries = [];
    fs.readdirSync(dir, { withFileTypes: true }).forEach(entry => {
        const fullPath = path.join(dir, entry.name);
        if (entry.isDirectory()) {
            entries.push(...walkDir(fullPath));
        } else {
            entries.push(fullPath);
        }
    });
    return entries;
}

2. 错误信息增强 ✅

优化内容：所有方法在 catch 时增加上下文信息（源路径、目标路径），便于调试时快速定位失败的压缩操作。

// 优化前：没有上下文
reject(e);
// 优化后：带有操作描述
reject(new Error(`[ZIP] 压缩文件夹失败: ${zipf} <- ${dir}: ${e.message}`));

🔜 待优化项目

| 优先级 | 问题 | 状态 | |--------|------|------| | 🟡 P2 | 统一 zip 和 zipstream 接口，内部自动选择策略 | 待处理 |

优化优先级总结

| 优先级 | 问题 | 影响 | |--------|------|------| | ✅ 已修复 | zipstream 不递归 | 功能缺陷 | | ✅ 已修复 | 错误信息增强 | 可调试性 |