JSZip API完全手册：从基础方法到高级应用

你还在为前端处理ZIP文件烦恼吗？JSZip作为JavaScript领域最强大的ZIP处理库，让浏览器端和Node.js环境下的ZIP文件创建、读取和编辑变得前所未有的简单。本文将从核心API到实战案例，全面解析JSZip的使用方法，帮助你轻松掌握文件压缩技术。读完本文，你将能够：创建自定义ZIP文件、解析现有压缩包、实现浏览器端文件下载，以及处理大文件流压缩等高级功能。

快速入门：JSZip核心概念

JSZip通过简洁的API抽象了复杂的ZIP文件操作。核心类JSZip代表一个ZIP文件实例，可通过file()和folder()方法管理文件和目录，最终通过generateAsync()生成ZIP数据或通过loadAsync()解析现有ZIP文件。

基础架构概览

graph TD
    A[JSZip实例] --> B[文件操作]
    A --> C[目录操作]
    A --> D[ZIP生成]
    A --> E[ZIP解析]
    B --> B1[添加文件 file()]
    B --> B2[读取文件 file()]
    B --> B3[删除文件 remove()]
    C --> C1[创建目录 folder()]
    D --> D1[generateAsync()]
    D --> D2[generateNodeStream()]
    E --> E1[loadAsync()]

安装与引入

浏览器环境（推荐使用国内CDN）：

<script src="https://cdn.bootcdn.net/ajax/libs/jszip/3.10.1/jszip.min.js"></script>

Node.js环境：

npm install jszip

const JSZip = require('jszip');

官方文档：README.markdown

核心API详解

JSZip构造函数

创建新的ZIP实例是所有操作的起点，支持无参数构造：

const zip = new JSZip();
// 或简化写法
const zip = JSZip();

构造函数文档：documentation/api_jszip/constructor.md

文件与目录操作

添加文件

使用file()方法添加文件，支持字符串内容、二进制数据或Base64编码：

// 添加文本文件
zip.file("hello.txt", "Hello World\n");

// 添加二进制文件（如图片）
zip.file("image.png", imageData, {base64: true});

// 添加目录结构
zip.file("docs/report.md", "# 项目报告");

创建目录

folder()方法创建虚拟目录，支持链式调用：

const images = zip.folder("images");
images.file("smile.gif", smileData, {base64: true});
// 等效于 zip.file("images/smile.gif", smileData, {base64: true})

文件属性

每个文件对应一个ZipObject实例，包含名称、目录标记、修改日期等元数据：

const file = zip.file("hello.txt");
console.log(file.name);      // "hello.txt"
console.log(file.dir);       // false
console.log(file.date);      // 最后修改日期对象
console.log(file.options.compression); // 压缩方式

ZipObject文档：documentation/api_zipobject.md

ZIP生成与下载

生成ZIP数据

generateAsync()方法支持多种输出格式，满足不同场景需求：

浏览器端常见用法

// 生成Blob对象并下载（推荐）
zip.generateAsync({type: "blob"})
  .then(function(blob) {
    saveAs(blob, "archive.zip"); // 需要FileSaver.js支持
  });

// 生成Base64编码（兼容性方案）
zip.generateAsync({type: "base64"})
  .then(function(base64) {
    location.href = "data:application/zip;base64," + base64;
  });

压缩选项配置

zip.generateAsync({
  type: "uint8array",
  compression: "DEFLATE",    // 压缩算法（STORE/DEFLATE）
  compressionOptions: {level: 9}, // 压缩级别（1-9）
  comment: "由JSZip生成的压缩包", // ZIP文件注释
  streamFiles: true          // 流式处理大文件
}, function updateCallback(metadata) {
  // 进度回调
  console.log(`进度: ${metadata.percent.toFixed(2)}%`);
  if (metadata.currentFile) {
    console.log(`正在处理: ${metadata.currentFile}`);
  }
});

generateAsync文档：documentation/api_jszip/generate_async.md

浏览器下载示例

JSZip提供多种浏览器下载方案，以下是基于Blob的实现：

<button id="downloadBtn">下载ZIP文件</button>
<script>
document.getElementById("downloadBtn").addEventListener("click", function() {
  const zip = new JSZip();
  zip.file("hello.txt", "Hello World!");
  
  zip.generateAsync({type: "blob"}).then(function(blob) {
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "example.zip";
    document.body.appendChild(a);
    a.click();
    setTimeout(() => {
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    }, 0);
  });
});
</script>

完整示例：documentation/examples/download-zip-file.html

ZIP文件解析

加载与解析ZIP

loadAsync()方法支持多种输入格式，轻松解析现有ZIP文件：

浏览器环境

// 从File对象加载（文件上传场景）
document.getElementById("fileInput").addEventListener("change", function(e) {
  const file = e.target.files[0];
  if (!file) return;
  
  const reader = new FileReader();
  reader.onload = function(e) {
    JSZip.loadAsync(e.target.result)
      .then(function(zip) {
        console.log("解析成功，文件列表:");
        console.log(Object.keys(zip.files));
      });
  };
  reader.readAsArrayBuffer(file);
});

Node.js环境

const fs = require("fs");
const JSZip = require("jszip");

fs.readFile("archive.zip", function(err, data) {
  if (err) throw err;
  JSZip.loadAsync(data).then(function(zip) {
    // 读取文本文件
    zip.file("config.txt").async("string").then(function(content) {
      console.log("配置内容:", content);
    });
  });
});

loadAsync文档：documentation/api_jszip/load_async.md

高级解析选项

JSZip.loadAsync(zipData, {
  checkCRC32: true,        // 验证文件CRC32校验和
  createFolders: true,     // 自动创建目录条目
  decodeFileName: function(bytes) {
    // 自定义文件名解码（处理特殊编码）
    return iconv.decode(bytes, "GBK");
  }
}).then(function(zip) {
  // 处理解析后的ZIP内容
});

实战案例

案例1：多文件合并下载

实现将多个文本文件打包为ZIP下载：

function downloadAsZip(files) {
  const zip = new JSZip();
  const folder = zip.folder("reports");
  
  files.forEach(file => {
    folder.file(file.name, file.content);
  });
  
  zip.generateAsync({type: "blob"})
    .then(blob => saveAs(blob, "reports.zip"));
}

// 使用示例
downloadAsZip([
  {name: "2023Q1.md", content: "# 第一季度报告..."},
  {name: "2023Q2.md", content: "# 第二季度报告..."}
]);

案例2：ZIP文件内容预览

解析上传的ZIP文件并展示内容结构：

<div id="fileList"></div>
<script>
function previewZip(file) {
  const reader = new FileReader();
  reader.onload = function(e) {
    JSZip.loadAsync(e.target.result).then(function(zip) {
      const fileList = document.getElementById("fileList");
      fileList.innerHTML = "<h3>ZIP内容:</h3><ul>";
      
      zip.forEach(function(relativePath, zipEntry) {
        const li = document.createElement("li");
        li.textContent = zipEntry.name + (zipEntry.dir ? "/" : "");
        li.style.paddingLeft = (zipEntry.name.split("/").length - 1) * 15 + "px";
        fileList.appendChild(li);
      });
      
      fileList.innerHTML += "</ul>";
    });
  };
  reader.readAsArrayBuffer(file);
}
</script>

案例代码参考：documentation/examples/read-local-file-api.html

案例3：大文件流式处理（Node.js）

处理大文件时使用流模式避免内存溢出：

const fs = require("fs");
const JSZip = require("jszip");

const zip = new JSZip();

// 添加大文件流
zip.file("large-file.dat", fs.createReadStream("path/to/large-file.dat"));

// 流式生成ZIP
zip.generateNodeStream({type: "nodebuffer", streamFiles: true})
  .pipe(fs.createWriteStream("large-archive.zip"))
  .on("finish", () => {
    console.log("大文件ZIP生成完成");
  });

性能优化与最佳实践

内存管理

• 处理大文件时始终启用streamFiles: true
• 及时释放不需要的ZipObject引用
• 避免在浏览器中处理超过100MB的ZIP文件

兼容性处理

// 检测浏览器支持情况
if (JSZip.support.uint8array) {
  // 使用Uint8Array格式
} else {
  // 降级为base64格式
}

支持信息文档：documentation/api_jszip/support.md

常见问题解决

1. 中文乱码问题：使用decodeFileName自定义解码
2. 大文件处理：启用流式处理并监控内存使用
3. 兼容性问题：对IE等旧浏览器使用FileSaver.js和Blob polyfill

总结与扩展

JSZip通过直观的API简化了复杂的ZIP文件操作，无论是前端文件下载、数据备份还是在线文档处理，都能提供高效可靠的解决方案。结合JSZip Utils等辅助库，可进一步扩展功能边界。建议深入阅读官方文档和示例代码，探索更多高级特性如ZIP64支持、加密文件处理等。

官方示例集合：documentation/examples.md

掌握JSZip，让你的Web应用轻松具备专业级文件压缩能力！如有疑问或需要更多示例，请查阅项目完整文档或提交issue参与社区讨论。