JSZip 局限性与边界指南：加密、ZIP64、性能与编码的完整解析-开发者社区

开发工具

【免费下载链接】jszip

Create, read and edit .zip files with Javascript

项目地址：https://gitcode.com/gh_mirrors/js/jszip

JSZip 是一个用 JavaScript 创建、读取和编辑 .zip 文件的库（见 README.markdown），但 zip 格式的完整规范非常庞大，并非所有特性都被支持。本文以官方 limitations.md 为骨架，结合 lib 目录下的源码实现与 test 目录中的测试用例，系统梳理 JSZip 在功能支持、数字精度、内存性能、压缩复用、元数据保留与字符编码六个维度的边界与应对方案，帮助你判断「哪些 zip 文件可以安全读取、哪些操作会产生非预期结果、出现瓶颈时如何绕行」。

一、不支持的 zip 特性：读取即失败

经典的普通 zip 文件可以正常工作，但 zip 规范中的部分高级特性 JSZip 没有实现。读取包含这些特性的文件时，loadAsync()会返回一个失败的 Promise（rejected promise），而不是静默地返回错误内容。

不支持的特性包括：

加密 zip（password protected / encrypted zip）：带密码保护的 zip 文件无法读取。
多卷 zip（multi-volume / split archive）：跨多个卷（disk）拆分的 zip 文件无法读取。
其他极端规格特性：只要某个 zip 使用了 JSZip 无法解析的结构，加载过程就会中止。

这一行为在源码中有明确实现：

在 lib/zipEntry.js 中，isEncrypted()通过检查通用位标志（general purpose bit flag）的第 1 位（bitFlag & 0x0001）判断条目是否加密；而在读取中央目录记录的 readCentralPart 中，一旦检测到加密，会直接抛出Error("Encrypted zip are not supported")，最终以 Promise 失败的形式暴露给调用方。
在 lib/zipEntries.js 的readBlockZip64EndOfCentralLocator中，读取 ZIP64 定位器时若disksCount > 1，会抛出Error("Multi-volumes zip are not supported")。

官方 API 文档 load_async.md 的「Zip features not (yet) supported」一节同样明确列出：password protected zip 与 multi-volume zip 目前均不受支持。仓库测试目录 test/ref 中的encrypted.zip、zip64.zip等参考文件也印证了这些边界场景是测试覆盖的重点。

二、ZIP64 与 32 位整数的根本限制

ZIP64 文件可以被加载，但前提是「文件不能太大」。这条限制源自 JavaScript 语言本身的数字模型，而非 JSZip 的实现缺陷：

JavaScript 的所有数字都以64 位双精度 IEEE 754 浮点数表示，整数部分只有53 位有效精度（ECMA-262 第 8.5 节）。
位运算（bitwise operations）在 JavaScript 中一律按32 位处理。

因此，只要 ZIP64 文件中所有 64 位整数都能塞进 32 位整数，一切正常；如果塞不进去，就会触发下一节描述的其他问题（内存、性能等）。

源码中处处体现着这一约束。在 lib/utils.js 中定义了两个边界常量：

exports.MAX_VALUE_16BITS = 65535; // 0xFFFF exports.MAX_VALUE_32BITS = -1; // 0xFFFFFFFF 被解析为 -1

在 lib/zipEntries.js 的readEndOfCentral中，只有当 EOCD（end of central directory）记录里的字段值达到0xFFFF/0xFFFFFFFF（即溢出占位符）时，才判定为 ZIP64 文件，然后继续寻找 ZIP64 EOCD 定位器与记录。紧随其后的源码注释直接复述了文档中的警告：ZIP64 扩展被支持，但仅当从文件中读出的 64 位整数能放进 32 位整数时——因为 JavaScript 把所有数字表示为 64 位双精度浮点数，整数只有 53 位，且位运算按 32 位处理。

同样，lib/zipEntry.js 的parseZIP64ExtraField在解析 ZIP64 扩展字段时也注释道：衷心希望这些 64 位整数能装进 32 位整数，因为 JS 不允许更多（"I really hope that these 64bits integer can fit in 32 bits integer, because js won't let us have more."）。

实用结论：对常规文件（单个文件小于 4GB、总条目数不超出 32 位范围）的 ZIP64 归档，JSZip 可以正常读取；真正的超大归档（超过 32 位整数范围）既无法可靠表示，也会在内存上撑不住。

三、性能限制：浏览器、内存与防卡顿

3.1 浏览器与机器的性能天花板

性能瓶颈很大程度上来自运行 JSZip 的浏览器（及其所在机器）。文档给出的经验数据是：一个10MB的压缩 zip，在 Firefox / Chrome / Opera / IE10+ 上可以轻松打开，但在更老的 IE 上会直接崩溃。

另一个被反复强调的内存隐患是 JavaScript 字符串的编码模型：JS 字符串按 UTF-16 编码，一个 10MB 的 ASCII 文本文件会占掉 20MB 内存（每个 ASCII 字符本应 1 字节，在 UTF-16 下变成 2 字节）。因此以字符串为中间形态处理二进制数据是非常浪费的。

3.2 async / generateAsync 全量驻留内存但不冻结浏览器

async方法（读取单个文件内容）与generateAsync方法（生成整个 zip）会在内存中持有完整结果。
好消息是它们内部基于流式 worker 实现，不会冻结浏览器（不阻塞 UI 线程）。
坏消息是结果太大时内存吃不消。

源码佐证：在 lib/zipObject.js 中，async(type, onUpdate)实际上是this.internalStream(type).accumulate(onUpdate)；而 lib/stream/StreamHelper.js 的accumulate会把所有 chunk 推入dataArray数组，最后一次性concat并transformZipOutput成完整结果——这正是「全量驻留内存」的实现来源。

3.3 超大结果的出路：nodeStream / generateNodeStream + StreamHelper

如果结果太大，且无法使用以下两种流式方案：

nodeStream方法（读取条目内容为 Node.js 流）
generateNodeStream方法（生成 zip 为 Node.js 流）

那么就必须退到底层的StreamHelper，逐块（chunk by chunk）处理结果，并配合pause()/resume()手动管理背压（backpressure）。这正是 lib/stream/StreamHelper.js 中on/resume/pause方法存在的意义：on("data", fn)以流方式接收每个 chunk，pause()暂停 chunk 流动，resume()恢复流动，从而把内存占用控制在单个 chunk 的规模而非整个文件。

四、官方性能建议与压缩机制的底层原理

4.1 官方建议清单

遇到性能问题时，按以下顺序排查：

不要使用 IE ≤ 9。typed arrays 是性能的关键，一切在 typed arrays 之上都会更好。
尽量使用 typed arrays（Uint8Array、ArrayBuffer 等）：
- 生成 zip 时，优先使用type: "uint8array"（或blob、arraybuffer、nodebuffer）。
- 通过 ajax 加载 zip 文件时，要求 XHR 返回ArrayBuffer（设置responseType: "arraybuffer"）。加载为字符串（string）等于自找麻烦——字符串的 UTF-16 编码与二进制处理都会带来额外的转换开销。

关于类型支持，可参考 lib/support.js 的运行时检测：base64、array、string恒为true，而arraybuffer、nodebuffer、uint8array、blob、nodestream取决于运行环境，生成时指定的type若不被平台支持，会通过utils.checkSupport（见 lib/utils.js）抛出xxx is not supported by this platform错误。

4.2 压缩复用的核心机制：读取不解压、生成不重压

关于压缩，文档给出两条关键规则：

读取文件时：JSZip 只存储压缩内容，不会解压。
生成压缩文件时：JSZip 会尽可能复用已有的压缩内容：
- 读取的是 DEFLATE 压缩的 zip，generate时也用 DEFLATE：不会调用压缩算法（同理，全 STORE 的情况也直接透传）。
- 读取的是 DEFLATE 压缩的 zip，generate时改用 STORE：必须解压全部内容再原样写入。

这一机制在源码中体现得淋漓尽致。在 lib/zipEntry.js 的readLocalPart中，读取到的压缩数据被直接封装为new CompressedObject(compressedSize, uncompressedSize, crc32, compression, rawData)，完全不经过解压。而在 lib/zipObject.js 的_compressWorker中：

_compressWorker: function (compression, compressionOptions) { if ( this._data instanceof CompressedObject && this._data.compression.magic === compression.magic ) { // 压缩方式相同：直接复用原始压缩数据，跳过压缩算法 return this._data.getCompressedWorker(); } else { // 压缩方式不同：必须先解压再重新压缩 var result = this._decompressWorker(); // ... return CompressedObject.createWorkerFrom(result, compression, compressionOptions); } }

可见「读 DEFLATE → 生成 DEFLATE」时走的是getCompressedWorker()快路径；「读 DEFLATE → 生成 STORE」时则走_decompressWorker()+ 重建的慢路径。另一个相关的官方提示在 generate_async.md 的compressionOptions一节：如果条目来自已压缩的 zip 文件，调用generateAsync()时指定不同的压缩级别并不会更新该条目——因为 JSZip 不知道内容当初被压缩到什么程度，无法把新的 level 与现有实现匹配。生成时使用的压缩算法只有STORE（不压缩）与DEFLATE两种，见 lib/compressions.js。

4.3 IE ≤ 9 的降级路径

在 IE ≤ 9 上，typed arrays 不受支持，压缩算法会回退到普通数组（Array）。此时 JSZip 被迫执行这样一条昂贵链路：把 binary string 转成数组 → DEFLATE 压缩 → 再把结果转回 binary string。文档的结论很直接：你不会想经历这个过程（"You don't want that to happen."）。这是支持旧浏览器场景下最应该规避的路径。

五、重新生成后的 zip 与原始 zip 必然不同

读取再生成一个 zip 文件，得到的不会是同一个文件。文档明确指出两类差异：

部分数据被丢弃（discarded）：例如文件元数据（file metadata）。JSZip 只保留它能理解的字段（日期、注释、UNIX/DOS 权限等，见 lib/zipObject.js 构造器对date、comment、unixPermissions、dosPermissions的收纳），其余无法映射的元数据在重写时自然消失。
部分数据被添加（added）：例如子文件夹（subfolders）会被显式补成目录条目。读取时若createFolders为false，路径中的目录仅作为「虚拟文件夹」存在（见 load_async.md 的createFolders一节）；而生成时路径结构会被完整写出。

因此在做「读入 → 修改 → 写出」这类编辑操作时，不要期望字节级一致，应把 JSZip 的输出视为「语义等价但结构重排」的新归档。

六、编码支持：仅原生支持 UTF-8

JSZip只原生支持 UTF-8。zip 规范的文件名/注释字段并不记录所用编码，你必须提前知道数据原本的编码，否则就会产生乱码（Mojibake）。

6.1 文件名与注释的编码

如果 zip 内文件名的编码是 UTF-8，JSZip 可以自动识别，依据是：

Language encoding flag（通用位标志的第 11 位）：见 lib/zipEntry.js 的useUTF8()，置位时直接走utf8.utf8decode（见handleUTF8，lib/zipEntry.js）。
Unicode Path Extra Field（0x7075）与 Unicode Comment Extra Field（0x6375）：见findExtraFieldUnicodePath/findExtraFieldUnicodeComment（lib/zipEntry.js），当普通路径不可用时，会优先尝试这些携带 UTF-8 版本名字的额外字段。

如果文件名不是UTF-8 编码，JSZip 无法探测实际编码，默认按 UTF-8 解码就会产生乱码。此时可以通过两个自定义回调解决：

encodeFileName（生成时）：传给generateAsync的选项，函数接收字符串、返回字节数组（Uint8Array 或 Array）。
decodeFileName（加载时）：传给loadAsync的选项，函数接收字节数组、返回解码后的字符串；默认值为utf8.utf8decode（见 lib/load.js 中 options 的默认值定义）。

典型示例（以 iconv-lite 处理 cp866 编码的文件名，示例取自 load_async.md）：

// 加载时：解码非 UTF-8 文件名 var iconv = require('iconv-lite'); zip.loadAsync(bin, { decodeFileName: function (bytes) { return iconv.decode(bytes, 'cp866'); } }); // 生成时：用自定义编码写文件名 zip.generateAsync({ type: 'uint8array', encodeFileName: function (string) { return iconv.encode(string, 'your-encoding'); } });

仓库测试 test/asserts/unicode.js 与 test/ref 下的utf8.zip、utf8_in_name.zip、winrar_utf8_in_name.zip、local_encoding_in_name.zip等参考归档，正是这些编码分支的验证样本。

6.2 文件内容的编码

async("string")方法默认按 UTF-8 解码文件内容。如果你要读一个非 UTF-8 编码的文本：

用async("uint8array")拿到原始字节数组；
用第三方库（iconv、iconv-lite 等）在自己的代码里解码。

反之，要把非 UTF-8 文本写入 zip：

先用 iconv 之类把字符串编码成Uint8Array；
再把Uint8Array作为内容交给 JSZip（JSZip 会原样保留二进制内容）。

这一「字节原样进出」的设计在 lib/zipObject.js 的internalStream中有完整呈现：当内容被标记为二进制（_dataBinary）而请求类型是字符串时，会自动接上utf8.Utf8DecodeWorker；当内容是 Unicode 字符串而请求类型是二进制时，则接上utf8.Utf8EncodeWorker。中间的字节流本身不被篡改，编码转换完全由调用方决定。

七、总结：边界意识是正确使用 JSZip 的前提

汇总所有限制与对应策略：

限制维度	具体表现	应对方式
不支持的格式	加密 zip、多卷 zip 读取即失败	加载前判断来源，捕获 rejected promise
数值精度	ZIP64 仅当 64 位整数可装入 32 位时可用	避免处理超大归档（>4GB 级别）
内存	字符串 UTF-16 翻倍、`async`/`generateAsync`全量驻留	用 typed arrays；超大结果改用流式 API +`pause()`/`resume()`
性能	IE ≤ 9 无 typed arrays，走数组降级路径	放弃 IE ≤ 9；XHR 请求 ArrayBuffer
压缩	同算法生成可复用压缩数据，跨算法必须解压重压	读/写使用相同压缩算法以获得最佳性能
元数据	重写会丢弃部分元数据、补写子文件夹条目	不要期望字节级往返一致
编码	仅原生 UTF-8，其他编码需手动处理	`decodeFileName`/`encodeFileName`+ iconv 类库

JSZip 的设计哲学是「在 JavaScript 的物理限制内，尽量高效地处理常规 zip」。理解并接受以上边界——而不是绕过它们——才能在实际项目中写出健壮、可预期的 zip 处理代码。如果你正准备在浏览器中下载 zip、或解析来自服务端的归档，建议同时阅读 howto/write_zip.md 与 howto/read_zip.md 两份实战指南，把本文的边界认知落到具体代码中。