ZIP 压缩与解压

ZIP 模块提供文件与目录的打包、解压，以及 GZIP 压缩、解压缩能力，常用于数据打包、日志归档、上传前压缩等场景。

说明：路径支持相对于当前脚本工作目录的相对路径（会自动通过 files.path() 解析），也支持绝对路径。压缩格式基于 java.util.zip，仅支持标准 ZIP（Deflate / Stored），不支持带密码加密的 ZIP。

zip.compress(source[, destination])

新增于：Hamibot 1.7.3

将文件或目录压缩为 ZIP。

• 当 source 为目录时，会递归压缩目录下的所有内容，并在压缩包内保留该目录名作为前缀；
• 当 source 为文件时，直接压缩该文件。

参数

名称	类型	描述
source	string	要压缩的文件或目录路径
destination	string	输出的 ZIP 文件路径，默认为 source + '.zip'

返回值

类型	描述
string	生成的 ZIP 文件路径

示例

// 压缩目录 /sdcard/demo，生成 /sdcard/demo.zip，内部条目带 demo/ 前缀
var path = zip.compress('/sdcard/demo');
log(path); // => /sdcard/demo.zip

// 指定输出路径
zip.compress('/sdcard/demo', '/sdcard/backup.zip');
hamibot.exit();

zip.decompress(source[, destination])

新增于：Hamibot 1.7.3

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

参数

名称	类型	描述
source	string	要解压的 ZIP 文件路径
destination	string	解压目标目录，默认为去掉 .zip 后缀的同名路径

返回值

类型	描述
string	解压目标目录路径

示例

// 解压到 /sdcard/demo
var dir = zip.decompress('/sdcard/demo.zip');
log(dir); // => /sdcard/demo

// 指定目录
zip.decompress('/sdcard/demo.zip', '/sdcard/restore');
hamibot.exit();

安全：解压时会校验每个条目的路径，若条目指向目标目录之外（恶意构造的 ../ 路径，即 zip slip 攻击），会直接抛出异常，避免文件被写入到非预期位置。

zip.unzip(source[, destination])

新增于：Hamibot 1.7.3

zip.decompress 的别名，参数与返回值完全相同。

zip.list(source)

新增于：Hamibot 1.7.3

列出 ZIP 文件中的所有条目名称。

参数

名称	类型	描述
source	string	ZIP 文件路径

返回值

类型	描述
Array<string>	条目名称数组

示例

log(zip.list('/sdcard/demo.zip')); // => ['demo/', 'demo/a.txt', 'demo/b.txt']
hamibot.exit();

zip.gzip(source[, destination])

新增于：Hamibot 1.7.3

使用 GZIP 压缩单个文件。

参数

名称	类型	描述
source	string	要压缩的文件路径
destination	string	输出的文件路径，默认为 source + '.gz'

返回值

类型	描述
string	生成的 .gz 文件路径

示例

var path = zip.gzip('/sdcard/big.log');
log(path); // => /sdcard/big.log.gz
hamibot.exit();

zip.gunzip(source[, destination])

新增于：Hamibot 1.7.3

解压 GZIP 文件。

参数

名称	类型	描述
source	string	要解压的 .gz 文件路径
destination	string	输出文件路径，默认为去掉 .gz 后缀的同名路径

返回值

类型	描述
string	解压后的路径

示例

var path = zip.gunzip('/sdcard/big.log.gz');
log(path); // => /sdcard/big.log
hamibot.exit();