更新记录

1.1.0（2026-07-19）

新增 XZ / BZIP2 解压 + 一键智能解压（extractAuto）——解压王格式再补齐。

• XZ 解压：unxzFile(src, dest) 单文件 .xz 解压，流式封顶防解压炸弹（超 256 MiB → 参数错误），坏 / 截断输入优雅报错、不崩溃。
• BZIP2 解压：unbzip2File(src, dest) 单文件 .bz2 解压，同款流式封顶 + 优雅报错。
• 一键智能解压：extractAuto(src, destDir) 按文件头自动识别格式并解压——zip / 7z / tar / tar.gz / tar.xz / tar.bz2 / gzip / xz / bzip2 通吃，内层是 tar 会自动继续解包；复用与 unzip 一致的 zip-slip 路径穿越防护 + zip-bomb 上限。RAR 明确不支持（遇 RAR 返回参数错误，不静默失败）。
• 支持格式扩至 9 类：zip / deflate、7z（含 AES256 加密）、tar、tar.gz、tar.xz、tar.bz2、gzip、xz、bzip2。
• API 面 14 → 17（新增 unxzFile / `unbzip2File

平台兼容性

uni-app x(5.14)

nex-archive —— 高性能压缩 / 解压（解压王）

自研高性能原生压缩 / 解压核心——zip / deflate + 7z + tar / tar.gz / tar.xz / tar.bz2 / gzip + xz / bzip2 全内置引擎，无额外系统依赖，提供 uni-app 可调的 JS API。 一键智能解压 extractAuto：按文件头自动识别格式，一行搞定 9 类归档。 仅支持 App 端（Android / iOS），H5 / 小程序加载不了原生库。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 全部「路径进 / 路径出」：源文件 / 目录 / zip 都传文件路径，原生层读写文件后返回结果，避免大 buffer 进 JS 层。

安全（本插件核心卖点之一：安全解压）

unzip 强制两道防线，不可关闭：

• zip-slip（路径穿越防护）：每个条目落点路径规范化后必须严格位于 destDir 内。含绝对路径、含 .. 逃逸、落点在 destDir 外的条目 → 返回 InvalidParam，绝不在 destDir 之外写出任何文件（条目名安全化 + 落点二次断言，双保险）。
• zip-bomb（解压炸弹上限）：累计解压字节上限 512 MiB、单条目上限 256 MiB、条目数上限 10000，任一超限 → InvalidParam 停止解压。既校验条目声明大小（快速预判），又对实际解压字节封顶（防 header 谎报），双重防 OOM / 撑爆磁盘。
• 绝不崩溃：坏 / 非 zip / IO 失败 → 错误返回（ArchiveError），绝不异常中断 App，全部可被 JS try/catch 捕获。

API

类型

// 压缩/解压结果（字段 camelCase）
type ArchiveResult = {
  entryCount: number; // 处理的条目数（压缩=文件数；解压=zip 内条目数）
  totalBytes: number; // 总未压缩载荷字节（压缩=各源文件字节之和；解压=写盘解压字节之和）
  costMs: number;     // 处理段耗时（毫秒）
};

• level：压缩级别 0-9（0 = 不压缩 Stored，1-9 = deflate）。超区间自动 clamp（负→0、>9→9），不报错。
• srcs 为空 → 参数错误；文件数 / zip 条目数 > 10000 → 参数错误。
• 坏 / 非 zip → zip 错误；源文件 / 目录不存在 → IO 错误。
• 错误经原生层 ArchiveException(Kotlin) / ArchiveError(Swift) 抛出（Io / InvalidParam / Zip），UTS 侧透传，可 try/catch。

用法

import { zipFiles, zipDir, unzip, listZip } from "@/uni_modules/nex-archive";

// 多文件打包（level 6）
const r1 = zipFiles(["/path/a.txt", "/path/b.png"], "/path/out.zip", 6);
// r1.entryCount === 2

// 整目录递归打包
const r2 = zipDir("/path/project", "/path/project.zip", 6);

// 安全解压（自动挡 zip-slip / zip-bomb）
const r3 = unzip("/path/out.zip", "/path/unpacked");
// r3.entryCount / r3.totalBytes

// 列出条目（不解压）
const names = listZip("/path/out.zip"); // string[]

加密 zip（AES-256）

import { zipFilesEncrypted, zipDirEncrypted, unzipEncrypted } from "@/uni_modules/nex-archive";

// 多文件打包成 AES-256 加密 zip（空口令 → 参数错误）
zipFilesEncrypted(["/path/a.txt", "/path/b.png"], "/path/secret.zip", "p@ssw0rd", 6);
// 整目录加密打包
zipDirEncrypted("/path/project", "/path/project.enc.zip", "p@ssw0rd", 6);

// 解密解压（复用 zip-slip / zip-bomb 守卫；错口令优雅报错）
const r = unzipEncrypted("/path/secret.zip", "/path/unpacked", "p@ssw0rd");
// 明文 zip 也可用 unzipEncrypted（口令被忽略，正常解出）—— 它是 unzip 的超集

7z / tar / gz（解压王）

import {
  un7z, list7z, untar, tarDir, listTar, gzipFile, gunzipFile,
} from "@/uni_modules/nex-archive";

// 安全解压 7z（明文：password 传 null；自动挡 zip-slip / zip-bomb）
const a = un7z("/path/in.7z", "/path/out7z", null);
const names7z = list7z("/path/in.7z"); // string[]，不解压

// tar / tar.gz —— untar 按 gzip magic 自动识别，无需关心扩展名
tarDir("/path/project", "/path/project.tar.gz", true);  // 打包成 tar.gz
const b = untar("/path/project.tar.gz", "/path/restored");
const namesTar = listTar("/path/project.tar.gz"); // string[]

// 单文件 gzip
gzipFile("/path/big.log", "/path/big.log.gz");
gunzipFile("/path/big.log.gz", "/path/big.log.restored");

XZ / BZIP2 解压 + 一键智能解压

import { unxzFile, unbzip2File, extractAuto } from "@/uni_modules/nex-archive";

// 单文件 XZ / BZIP2 解压（流式封顶防解压炸弹；坏 / 截断输入优雅报错、不崩溃）
unxzFile("/path/data.xz", "/path/data");
unbzip2File("/path/data.bz2", "/path/data");

// 一键智能解压 —— 不用关心是什么格式，按文件头自动识别并解压
// zip / 7z / tar / tar.gz / tar.xz / tar.bz2 / gzip / xz / bzip2 通吃，内层 tar 会自动继续解包
const r = extractAuto("/path/whatever.archive", "/path/out");
// 复用与 unzip 一致的 zip-slip + zip-bomb 防护；遇 RAR 返回参数错误（明确不支持，不静默失败）

平台与调试边界

• 仅 app-android / app-ios；H5、各家小程序不支持。
• Android 本地真机调试原生库需 HBuilderX ≥ 4.26（自定义调试基座），云打包不受此限。
• iOS 端原生库含 Swift，宿主原生工程需开启「支持 Swift」。
• 最终 App 打包由 HBuilderX / @dcloudio CLI 完成。

范围说明

• 支持格式：zip / deflate、7z（LZMA/LZMA2 + AES256 加密）、tar、tar.gz / tar.xz / tar.bz2 / gzip、xz、bzip2——均为内置引擎实现，无额外系统依赖。
• 加密 7z（口令）已支持：内置 AES256 解密实现；un7z 传口令解密 AES256 加密 7z（明文 7z 传 null 正常解）；口令错误优雅报错、不崩溃、不静默解出原文。
• XZ / BZIP2 解压已支持：unxzFile / unbzip2File 单文件解压，流式封顶防解压炸弹；extractAuto 与 untar 亦自动识别 .xz / .bz2 / .tar.xz / .tar.bz2。仅解压方向（本插件不产 .xz / .bz2）。
• RAR 暂不支持：extractAuto 遇 RAR 明确返回参数错误（不静默失败、不误分派）。
• 加密 zip（AES-256）已支持：内置 AES / HMAC / PBKDF2 加密实现；zipFilesEncrypted / zipDirEncrypted 产 WinZip AE-2 加密 zip，unzipEncrypted 解密解压并复用同一套 zip-slip + zip-bomb 守卫；写侧空口令 → 参数错误，读侧错口令优雅报错（不崩溃、不静默解出）。
• 流式超大文件不在本期范围：常规大小文件受解压侧 512 MiB 累计 / 256 MiB 单条目上限约束（zip / 7z / tar / gz / xz / bzip2 同口径）。注：.tar.xz 的内层 tar 会先有界解压进内存（受 512 MiB 上限封顶）再解包，移动端峰值内存比 .tar.gz / .tar.bz2 的流式解压略重，但不会无界。
• un7z / untar / unxzFile / unbzip2File / extractAuto 沿用与 unzip 完全一致的 zip-slip 防护 + zip-bomb 上限；untar 额外自校验每个 entry.path()（不信任 tar 自带 unpack），符号链接 / 硬链接等特殊条目一律跳过。