JSZip API完全手册：从基础方法到高级应用
项目地址: https://gitcode.com/gh_mirrors/js/jszip 你还在为前端处理ZIP文件烦恼吗？JSZip作为JavaScript领域最强大的ZIP处理库，让浏览器端和Node.js环境下的ZIP文件创建、读取和编辑变得前所未有的简单。本文将从核心API到实战案例，全面解析JSZip的使用方法，帮助你轻松掌握文件压缩技术。读完本文，你将能够：创建自定义ZIP文件、解析现有压缩包、实现浏览器端文件下载，以及处理大文件流压缩等高级功能。
快速入门：JSZip核心概念
JSZip通过简洁的API抽象了复杂的ZIP文件操作。核心类JSZip代表一个ZIP文件实例，可通过file()和folder()方法管理文件和目录，最终通过generateAsync()生成ZIP数据或通过loadAsync()解析现有ZIP文件。
基础架构概览
安装与引入
浏览器环境（推荐使用国内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
常见问题解决
- 中文乱码问题：使用
decodeFileName自定义解码 - 大文件处理：启用流式处理并监控内存使用
- 兼容性问题：对IE等旧浏览器使用FileSaver.js和Blob polyfill
总结与扩展
JSZip通过直观的API简化了复杂的ZIP文件操作，无论是前端文件下载、数据备份还是在线文档处理，都能提供高效可靠的解决方案。结合JSZip Utils等辅助库，可进一步扩展功能边界。建议深入阅读官方文档和示例代码，探索更多高级特性如ZIP64支持、加密文件处理等。
官方示例集合：documentation/examples.md
掌握JSZip，让你的Web应用轻松具备专业级文件压缩能力！如有疑问或需要更多示例，请查阅项目完整文档或提交issue参与社区讨论。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
