简介针对Cocos Creator开发者在游戏资源打包、更新与数据存储中常见的压缩文件需求提供一套基于JSZip库的ZIP处理方案包含读取、解压、创建与跨平台适配的核心逻辑。资源包内共25个文件主要包含JavaScript脚本.js、配置文件.json、原生桥接源码.cpp/.hpp/.h、Cocos Creator场景与元数据.fire/.meta等整体大小仅43KB属于轻量级演示工程。内容从ZIP基本概念入手详细说明如何通过npm引入JSZip、用fetch或XMLHttpRequest加载二进制数据、通过loadAsync完成解压以及使用readAsText/readAsDataURL读取文件条目同时介绍生成ZIP文件、选择压缩级别与输出格式的完整流程并针对Web与原生平台差异、浏览器安全限制等给出注意事项。还结合游戏资源增量更新、可下载扩展内容、存档打包上传等场景说明实际应用方式。已有1144人学习浏览适合希望快速在Cocos Creator中实现ZIP文件读写与管理的初中级开发者参考。1. 项目里为什么绕不开zip四个高频场景与方案选型做Cocos Creator项目只要不是那种纯Demo级的单场景小游戏“zip文件处理”基本都会找上门来。我最早遇到zip是在做热更新的时候之后做资源分包、离线包、存档导出前后踩了不少坑也积累了一套比较顺手的处理方式。说句实话zip在游戏项目里不是什么高深技术但用不好真的会卡研发进度尤其是跨平台打包之后解压失败、路径找不到、中文乱码这些故障轮流来。先别急着写代码我们得先弄清楚zip在Cocos Creator里到底解决什么问题以及不同场景下该选哪套方案。1.1 热更新资源包zip的保留节目Cocos Creator做的游戏上架后如果资源需要动态更新zip压缩包几乎是绕不开的存储格式。热更服务器上放的资源包通常就是zip文件客户端下载下来之后解压到可写目录再通过assetManager动态加载。这里zip承担的是“传输体积优化”的角色合理压缩能把包体缩小30%到60%。我见过不少团队直接用一个远程目录塞散文件不用zip包。这样做的后果是文件数量多的时候下载慢传输请求频繁而且服务器上文件管理混乱。打包成zip后一次请求就能拿到整批资源效率高很多。1.2 资源分发、离线包和存档导出除了热更新zip还有几个常见的应用场景。一是离线包。部分中重度游戏会把首包之外的资源整体做成离线zip玩家首次进入游戏时先解压到本地后续加载资源走本地路径。这种做法适合包体受限、但游戏内容较多的项目。二是存档导出。我做过一个单机向项目玩家存档需要支持导出和导入当时就是把存档目录整个压成一个zip文件再引导用户保存到外部存储。反过来导入时解压zip覆盖存档目录即可。三是批量资源导入。比如编辑器环境下的美术资源批量导入、关卡编辑器的数据包分发这些也可以借助zip完成。Cocos Creator编辑器本身就支持导入zip资源包所以这个方向在工具链层面也是通的。1.3 原生zip还是JSZip我这样选Cocos Creator项目处理zip主流方案大致有两种原生扩展minizip/zlib和纯TS方案JSZip。原生扩展说白了就是写C代码用Jsb桥接给TypeScript调用。优点是性能好、占用内存低适合大文件解压缺点是需要编译原生工程发布时各平台都要处理调试链路比较长。JSZip是纯JavaScript实现的zip库可以直接在TypeScript里调用发布到Web和小游戏平台非常方便不需要额外编译原生代码。缺点是解压大文件时内存占用偏高而且小游戏平台对包体有要求集成JSZip本身也要占用一些体积。我个人的选型经验是如果项目同时涉及Web和原生优先用JSZip因为它一套代码通吃所有平台省掉很多平台适配的精力如果项目只在原生端跑且解压的文件动辄几十上百MB那原生minizip方案更稳。也有人用“双轨方案”原生端走minizipWeb/小游戏端走JSZip代码里做平台判断这样性能体验更均衡但维护成本也会相应增加。提示不管选哪个方案都建议把zip操作封装成独立模块对外只暴露统一的接口。这样以后换库、加缓存、加解密逻辑都不需要动业务代码。2. 解压zip的完整实操从读取到释放一步不落选定方案后真正的难点在于把解压这件事做扎实。我遇到很多“解压失败”的问题其实不是库的问题而是目录没有提前创建、编码没处理好、资源没有释放或者文件名里带了特殊字符。2.1 准备阶段目录规划比代码更重要解压zip之前先想清楚解压到哪里。Cocos Creator 3.x中原生平台的持久化路径建议使用native.getUserDataPath()Web平台通常使用浏览器沙箱存储小游戏平台则指向各自的用户数据目录。一个比较稳妥的目录结构如下userDataPath/ ├── hotupdate/ │ ├── version_1.0.1.zip │ └── unpacked/ │ └── assets/ └── sav/ └── archive_20240501.zip把zip文件和解压目录分开管理的好处是解压前可以先校验zip文件完整性解压过程中如果出现异常可以删除半成品目录重新来过。我习惯在解压前先创建目标目录并且每次解压前清空上一次的残留内容避免旧文件干扰新版本。2.2 核心解压代码minizip版本原生端我用的是minizip它在zlib基础上封装了zip和unzip的API使用起来比较直观。下面是一段精简的解压代码按条目遍历zip包逐文件写入目标路径// ZipHelper.cpp #include ZipHelper.h #include unzip.h #include zlib.h #include filesystem bool ZipHelper::unzipToFolder(const std::string zipPath, const std::string outPath) { unzFile zipFile unzOpen(zipPath.c_str()); if (!zipFile) { return false; } unz_global_info globalInfo; if (unzGetGlobalInfo(zipFile, globalInfo) ! UNZ_OK) { unzClose(zipFile); return false; } std::filesystem::create_directories(outPath); unz_file_info fileInfo; char fileName[256]; for (int i 0; i globalInfo.number_entry; i) { if (unzGetCurrentFileInfo(zipFile, fileInfo, fileName, sizeof(fileName), nullptr, 0, nullptr, 0) ! UNZ_OK) { unzClose(zipFile); return false; } std::string fullPath outPath / fileName; if (fileName[strlen(fileName) - 1] /) { // 目录项直接创建目录 std::filesystem::create_directories(fullPath); } else { // 文件项确保父目录存在 std::filesystem::create_directories(std::filesystem::path(fullPath).parent_path()); if (unzOpenCurrentFile(zipFile) ! UNZ_OK) { unzClose(zipFile); return false; } FILE* outFile fopen(fullPath.c_str(), wb); if (!outFile) { unzCloseCurrentFile(zipFile); unzClose(zipFile); return false; } char buffer[8192]; int readBytes 0; while ((readBytes unzReadCurrentFile(zipFile, buffer, sizeof(buffer))) 0) { fwrite(buffer, 1, readBytes, outFile); } fclose(outFile); unzCloseCurrentFile(zipFile); } if (i 1 globalInfo.number_entry) { if (unzGoToNextFile(zipFile) ! UNZ_OK) { unzClose(zipFile); return false; } } } unzClose(zipFile); return true; }这段代码在TypeScript层通过Jsb桥接调用暴露给业务层时大概长这样import { native } from cc; export function unzip(zipPath: string, outPath: string): boolean { if (native.isNative) { return native.bridge.call(zipHelper, unzipToFolder, zipPath, outPath); } // Web端走JSZip逻辑 return unzipOnWeb(zipPath, outPath); }有几个细节我必须强调一下。第一unzReadCurrentFile的缓冲区大小我用的是8192字节这个值可以根据实际场景调整大文件可以放大到64KB解压速度会有明显提升。第二遍历条目时一定要判断unzGoToNextFile的返回值否则到zip包末尾时可能会出现意外行为。第三写文件时用wb模式不要用w否则在Windows平台上二进制数据会被截断。2.3 浏览器和小游戏端用JSZip兜底Web端和微信小游戏端没有原生文件系统我通常用JSZip来处理解压。JSZip的核心API是loadAsync传给它ArrayBuffer或Blob然后遍历文件列表逐个写入。小游戏端的代码大致如下import JSZip from jszip; export async function unzipOnMiniGame(arrayBuffer: ArrayBuffer, outDir: string): Promisevoid { const zip await JSZip.loadAsync(arrayBuffer); const fs wx.getFileSystemManager(); // 先确保根目录存在 fs.mkdirSync(outDir, true); for (const relativePath of Object.keys(zip.files)) { const entry zip.files[relativePath]; const fullPath outDir / relativePath; if (entry.dir) { fs.mkdirSync(fullPath, true); } else { // 确保父目录存在 const parentDir fullPath.substring(0, fullPath.lastIndexOf(/)); fs.mkdirSync(parentDir, true); const content await entry.async(uint8array); fs.writeFileSync(fullPath, content, binary); } } }这里要注意mkdirSync的第二个参数recursive在小游戏基础库低版本上可能不支持所以保险起见写文件前逐级创建父目录虽然多写几行代码但兼容性好很多。2.4 隐藏比较深的两个问题编码和内存第一个问题是中文文件名乱码。zip格式本身没有强制规定文件名编码Windows上压缩工具默认用GBKmacOS/Linux上大多用UTF-8。Cocos Creator在原生端拿到GBK编码的文件名时直接按UTF-8解析就会乱码。处理思路有两种一种是在压缩时就统一文件名编码团队内部约定使用UTF-8另一种是在解压时做编码判断和转换检测到非UTF-8时做编码转换。第一种方式成本最低但需要约束资源打包流程第二种方式兼容性更好适合解压来自外部系统的zip包。第二个问题是内存。JSZip在解压大文件时会把整个文件内容读取到内存中如果zip里放的是一个100MB的资源包内存峰值会非常吓人。原生minizip按块读取就没有这个问题。所以我的建议是大文件场景别用JSZip或者把zip里的资源按子目录拆分一次只解压需要的那一部分。3. 反过来生成zip与加密打包、密码与安全边界解压只解决了一半问题实际项目中经常还需要“把资源打包成zip”。比如导出存档、制作离线资源包、服务器端生成热更包这些都要用到zip的“写”能力。3.1 用minizip把游戏资源打包成zipminizip创建zip包的核心流程是打开zip文件逐个添加条目把数据写入最后关闭。下面是一段简化的打包代码bool ZipHelper::zipFolder(const std::string srcPath, const std::string zipPath, int compressLevel) { zipFile zip zipOpen(zipPath.c_str(), APPEND_STATUS_CREATE); if (!zip) return false; // 递归遍历srcPath下的所有文件逐个添加进zip for (const auto entry : std::filesystem::recursive_directory_iterator(srcPath)) { if (entry.is_directory()) { continue; } std::string fullPath entry.path().string(); // 计算相对路径作为zip内的条目名 std::string relativePath std::filesystem::relative(entry.path(), srcPath).string(); std::replace(relativePath.begin(), relativePath.end(), \\, /); // 读取文件内容并写入zip FILE* file fopen(fullPath.c_str(), rb); fseek(file, 0, SEEK_END); long fileSize ftell(file); fseek(file, 0, SEEK_SET); char* buffer new char[fileSize]; fread(buffer, 1, fileSize, file); fclose(file); zipOpenNewFileInZip(zip, relativePath.c_str(), nullptr, nullptr, 0, nullptr, 0, created by game client, Z_DEFLATED, compressLevel); zipWriteInFileInZip(zip, buffer, fileSize); zipCloseFileInZip(zip); delete[] buffer; } zipClose(zip, created by game client); return true; }打包时有一个容易忽略的细节zip内的条目名要统一使用正斜杠/不要用反斜杠\。Cocos Creator在加载zip内的资源时对路径分隔符的处理是敏感的Windows路径风格在Android和iOS上会引发“文件找不到”的问题。3.2 密码保护和AES加密设密前先想清楚zip本身支持设置密码minizip也提供了zipOpenNewFileInZip时传入密码参数的能力。但要注意传统的zip密码加密方式是ZipCrypto安全性较弱而且在一些解压工具上无法直接打开。minizip的AES扩展如aes-xamarin、aescrypt能提供更可靠的加密但兼容性需要额外验证。我个人的建议是如果zip只是防止“误打开”用传统密码就够了如果资源本身需要严格保密不要把安全寄托在zip密码上应该在业务层做加密处理。比如对zip包内的敏感资源先做AES加密再打包成zip解压后还要在代码里解密这样才能保证资源在没有密码的情况下不会被直接提取。3.3 压缩级别怎么选别拿游戏耗电开玩笑minizip的Z_DEFLATED压缩级别是0到90是不压缩9是最高压缩。很多新手喜欢直接用9觉得压缩率越高越好实际上在移动端会带来明显的CPU占用。压缩级别每提高1级CPU耗时可能增加20%到50%而体积节省可能只有几个百分点。我做热更包时实践下来觉得Z_DEFLATED配合6级压缩是一个比较均衡的状态体积不算大打包速度也扛得住。如果是纹理、音频这类本来就压缩过的文件压缩收益很小甚至可以直接用0级纯存储能大幅提升打包速度。4. 打包apk时zip的处理策略放包里还是放外部“cocos creator 打包apk”是搜索热度很高的话题很多问zip文件处理的其实是在纠结打包阶段zip放哪里。4.1 打进apk的zip与首次启动释放有些团队会把一个包含初始资源的zip放进apk的assets目录游戏首次启动时再解压到用户目录。这个做法的出发点是减少apk中的文件数量让安装包在文件系统上更整洁同时避免一些平台对大量小文件的IO性能损耗。关键坑在于assets目录在Android上是只读的不能直接在里面解压。正确做法是先把assets里的zip复制到getUserDataPath()对应的可写目录再执行解压。有同行图省事直接把assets路径传给解压函数结果解压失败排查了很久才发现是只读目录的问题。复制完成后还有一步很关键拷贝出来后经过解压assets里那份zip就没用了需要及时删除避免重复占用地盘。4.2 热更新目录下的zip落地与版本控制如果走热更新流程服务器下发的zip包建议统一放在一个独立目录并且以版本号命名。这样随时可以回到旧版本出问题也方便排查。我习惯在下载zip后先做两件事校验MD5再解压。校验在下载完成之后就做解压之前再校验一次写入磁盘的文件是否完整。这个习惯帮我挡住过不少次“下载到一半网络断了但文件大小刚好一致”的诡异问题。async function downloadAndApplyZip(url: string, version: string): Promisevoid { const zipPath path.join(native.getUserDataPath(), hotupdate, ${version}.zip); const outPath path.join(native.getUserDataPath(), hotupdate, unpacked_${version}); // 1. 下载zip await downloadFile(url, zipPath); // 2. 校验MD5 const remoteMd5 await getRemoteMd5(url .md5); const localMd5 computeFileMd5(zipPath); if (remoteMd5 ! localMd5) { throw new Error(zip md5 mismatch); } // 3. 解压 const ok unzip(zipPath, outPath); if (!ok) { throw new Error(unzip failed); } // 4. 加载解压后的bundle await assetManager.loadBundle(outPath /assets); }这段流程看似简单但每一步都可能出问题。比如MD5接口挂了比如解压到一半杀进程比如下一个版本的上一个版本还占着资源。所以热更zip的命名、路径、清理策略一定要在一开始就设计好否则越到后面越难受。4.3 别偷懒版本号与文件清单双管齐下依靠zip文件名做版本是不可靠的。包内的资源文件可能有增删而zip本身没有版本概念。我的经验是在zip包内额外放一个version.json记录当前资源的版本号、文件清单、MD5列表。解压时先读version.json再逐一比对文件是否存在、大小是否正确这样能最大程度避免“解压成功但加载失败”的情况。{ version: 1.0.12, files: { assets/bundle1/config.json: d41d8cd98f00b204e9800998ecf8427e, assets/bundle1/scene.scene: s3g2hk3h2k3h2k3h2k3, assets/bundle1/textures/hero.png: a1b2c3d4e5f6a7b8c9d0 } }校验清单的好处是一旦某个文件损坏可以精准定位到具体是哪个文件然后重新下载或修复而不是整个zip重新来一遍。5. 高频报错排查解压失败、文件找不到、中文乱码最后这部分我把自己和身边同事踩过的高频问题整理成一个排查清单希望对你有实际帮助。5.1 invalid zip archivecould not find eocd 的排查路径“invalid zip archive: could not find eocd”这个错误在导入资源包、加载zip、解压zip时都可能会出现。EOCD是zip文件末尾的中央目录结束标识报这个错说明文件尾部没有找到正确的zip结构。常见原因和排查路径如下文件不是真正的zip格式。很多网络上下载的“zip”其实是自解压格式或7z格式只是改了扩展名。用十六进制工具看一眼文件头部zip文件头是以PK开头的。下载不完整。文件传输过程中断导致zip文件末尾的EOCD缺失。重新下载并加上MD5校验。zip文件包含双重卷标或由特殊工具生成与解压库不兼容。尽量使用标准zip格式生成。Cocos Creator编辑器导入资源包时zip内文件路径过长或包含特殊字符导致编辑器解析失败。重新压缩保持文件名简洁。遇到这个错误第一步一定是确认文件完整性不要先怀疑代码。5.2 FileNotFoundException与copy失败常见原因Cocos Creator原生端报“FileNotFoundException”十有八九是路径问题。常见的几种情况目标目录不存在。解压前没有创建目录或者目录创建被系统拦截。检查getUserDataPath()返回的路径是否真的可写。相对路径和绝对路径混用。原生端建议一律使用绝对路径拼接目录用cc.path.join而不是手写字符串加号。小游戏端文件系统API不同。微信小游戏不能直接使用cc.sys.localStorage或原生文件API必须通过wx.getFileSystemManager()操作。Android上外置存储的权限问题。部分Android版本对外置SD卡写入有权限限制最好统一使用应用私有目录。5.3 GBK中文文件名乱码怎么治解压出来的文件名乱码我遇到的基本都是GBK编码问题。解决思路是在minizip解压时拿到文件名后不直接使用而是做一次编码转换。如果项目中的zip包全部由自己工具生成强烈建议统一为UTF-8文件名这是一劳永逸的办法。如果必须兼容外部系统打包的zip那么需要在解压环节增加编码识别逻辑先看zip包的flag位是否标记UTF-8如果没有标记且包含了非ASCII字符则按GBK解码。bool skipUtf8Check (fileInfo.flag 0x800) ! 0; if (!skipUtf8Check) { // 尝试将GBK转成UTF-8 std::string utf8Name convertGbkToUtf8(fileName); strcpy(fileName, utf8Name.c_str()); }5.4 问题速查表现象可能原因处理方式解压报invalid zip archive文件下载不完整或格式不对校验MD5、确保是标准zip格式解压后文件缺失zip内目录项与文件项顺序异常遍历时创建所有父目录Native端FileNotFoundException目标目录不存在解压前递归创建目录Web端解压内存暴涨大文件全部读入内存不用JSZip处理超大文件中文文件名乱码GBK/UTF-8编码不一致统一UTF-8或做编码转换推动apk后zip不存在写在只读目录assets里先复制到可写目录再操作下载的zip无法导入编辑器压缩工具生成了不兼容格式用标准zip避免自解压格式根据我的个人经验在Cocos Creator里处理和zip有关的需求最核心的还是“路径、编码、异步释放”这三件事。路径要统一规划编码要明确约定资源释放要及时。这三点做好了zip翻车的概率就会大幅下降。最后分享一个小技巧把zip的下载、校验、解压、加载这一整个流程封装成一个Promise链式函数内部处理所有平台差异和异常分支。项目里所有需要zip的场景复用这个函数既能少写很多重复代码遇到问题也只需要在一个地方修复比到处贴解压代码要省心得多。本文还有配套的精品资源点击获取 
长河君 · 2026/9/9 14:18:32 · 阅读 1.2k Cocos Creator中的zip处理完全指南：解压、打包与跨平台避坑
简介针对Cocos Creator开发者在游戏资源打包、更新与数据存储中常见的压缩文件需求提供一套基于JSZip库的ZIP处理方案包含读取、解压、创建与跨平台适配的核心逻辑。资源包内共25个文件主要包含JavaScript脚本.js、配置文件.json、原生桥接源码.cpp/.hpp/.h、Cocos Creator场景与元数据.fire/.meta等整体大小仅43KB属于轻量级演示工程。内容从ZIP基本概念入手详细说明如何通过npm引入JSZip、用fetch或XMLHttpRequest加载二进制数据、通过loadAsync完成解压以及使用readAsText/readAsDataURL读取文件条目同时介绍生成ZIP文件、选择压缩级别与输出格式的完整流程并针对Web与原生平台差异、浏览器安全限制等给出注意事项。还结合游戏资源增量更新、可下载扩展内容、存档打包上传等场景说明实际应用方式。已有1144人学习浏览适合希望快速在Cocos Creator中实现ZIP文件读写与管理的初中级开发者参考。1. 项目里为什么绕不开zip四个高频场景与方案选型做Cocos Creator项目只要不是那种纯Demo级的单场景小游戏“zip文件处理”基本都会找上门来。我最早遇到zip是在做热更新的时候之后做资源分包、离线包、存档导出前后踩了不少坑也积累了一套比较顺手的处理方式。说句实话zip在游戏项目里不是什么高深技术但用不好真的会卡研发进度尤其是跨平台打包之后解压失败、路径找不到、中文乱码这些故障轮流来。先别急着写代码我们得先弄清楚zip在Cocos Creator里到底解决什么问题以及不同场景下该选哪套方案。1.1 热更新资源包zip的保留节目Cocos Creator做的游戏上架后如果资源需要动态更新zip压缩包几乎是绕不开的存储格式。热更服务器上放的资源包通常就是zip文件客户端下载下来之后解压到可写目录再通过assetManager动态加载。这里zip承担的是“传输体积优化”的角色合理压缩能把包体缩小30%到60%。我见过不少团队直接用一个远程目录塞散文件不用zip包。这样做的后果是文件数量多的时候下载慢传输请求频繁而且服务器上文件管理混乱。打包成zip后一次请求就能拿到整批资源效率高很多。1.2 资源分发、离线包和存档导出除了热更新zip还有几个常见的应用场景。一是离线包。部分中重度游戏会把首包之外的资源整体做成离线zip玩家首次进入游戏时先解压到本地后续加载资源走本地路径。这种做法适合包体受限、但游戏内容较多的项目。二是存档导出。我做过一个单机向项目玩家存档需要支持导出和导入当时就是把存档目录整个压成一个zip文件再引导用户保存到外部存储。反过来导入时解压zip覆盖存档目录即可。三是批量资源导入。比如编辑器环境下的美术资源批量导入、关卡编辑器的数据包分发这些也可以借助zip完成。Cocos Creator编辑器本身就支持导入zip资源包所以这个方向在工具链层面也是通的。1.3 原生zip还是JSZip我这样选Cocos Creator项目处理zip主流方案大致有两种原生扩展minizip/zlib和纯TS方案JSZip。原生扩展说白了就是写C代码用Jsb桥接给TypeScript调用。优点是性能好、占用内存低适合大文件解压缺点是需要编译原生工程发布时各平台都要处理调试链路比较长。JSZip是纯JavaScript实现的zip库可以直接在TypeScript里调用发布到Web和小游戏平台非常方便不需要额外编译原生代码。缺点是解压大文件时内存占用偏高而且小游戏平台对包体有要求集成JSZip本身也要占用一些体积。我个人的选型经验是如果项目同时涉及Web和原生优先用JSZip因为它一套代码通吃所有平台省掉很多平台适配的精力如果项目只在原生端跑且解压的文件动辄几十上百MB那原生minizip方案更稳。也有人用“双轨方案”原生端走minizipWeb/小游戏端走JSZip代码里做平台判断这样性能体验更均衡但维护成本也会相应增加。提示不管选哪个方案都建议把zip操作封装成独立模块对外只暴露统一的接口。这样以后换库、加缓存、加解密逻辑都不需要动业务代码。2. 解压zip的完整实操从读取到释放一步不落选定方案后真正的难点在于把解压这件事做扎实。我遇到很多“解压失败”的问题其实不是库的问题而是目录没有提前创建、编码没处理好、资源没有释放或者文件名里带了特殊字符。2.1 准备阶段目录规划比代码更重要解压zip之前先想清楚解压到哪里。Cocos Creator 3.x中原生平台的持久化路径建议使用native.getUserDataPath()Web平台通常使用浏览器沙箱存储小游戏平台则指向各自的用户数据目录。一个比较稳妥的目录结构如下userDataPath/ ├── hotupdate/ │ ├── version_1.0.1.zip │ └── unpacked/ │ └── assets/ └── sav/ └── archive_20240501.zip把zip文件和解压目录分开管理的好处是解压前可以先校验zip文件完整性解压过程中如果出现异常可以删除半成品目录重新来过。我习惯在解压前先创建目标目录并且每次解压前清空上一次的残留内容避免旧文件干扰新版本。2.2 核心解压代码minizip版本原生端我用的是minizip它在zlib基础上封装了zip和unzip的API使用起来比较直观。下面是一段精简的解压代码按条目遍历zip包逐文件写入目标路径// ZipHelper.cpp #include ZipHelper.h #include unzip.h #include zlib.h #include filesystem bool ZipHelper::unzipToFolder(const std::string zipPath, const std::string outPath) { unzFile zipFile unzOpen(zipPath.c_str()); if (!zipFile) { return false; } unz_global_info globalInfo; if (unzGetGlobalInfo(zipFile, globalInfo) ! UNZ_OK) { unzClose(zipFile); return false; } std::filesystem::create_directories(outPath); unz_file_info fileInfo; char fileName[256]; for (int i 0; i globalInfo.number_entry; i) { if (unzGetCurrentFileInfo(zipFile, fileInfo, fileName, sizeof(fileName), nullptr, 0, nullptr, 0) ! UNZ_OK) { unzClose(zipFile); return false; } std::string fullPath outPath / fileName; if (fileName[strlen(fileName) - 1] /) { // 目录项直接创建目录 std::filesystem::create_directories(fullPath); } else { // 文件项确保父目录存在 std::filesystem::create_directories(std::filesystem::path(fullPath).parent_path()); if (unzOpenCurrentFile(zipFile) ! UNZ_OK) { unzClose(zipFile); return false; } FILE* outFile fopen(fullPath.c_str(), wb); if (!outFile) { unzCloseCurrentFile(zipFile); unzClose(zipFile); return false; } char buffer[8192]; int readBytes 0; while ((readBytes unzReadCurrentFile(zipFile, buffer, sizeof(buffer))) 0) { fwrite(buffer, 1, readBytes, outFile); } fclose(outFile); unzCloseCurrentFile(zipFile); } if (i 1 globalInfo.number_entry) { if (unzGoToNextFile(zipFile) ! UNZ_OK) { unzClose(zipFile); return false; } } } unzClose(zipFile); return true; }这段代码在TypeScript层通过Jsb桥接调用暴露给业务层时大概长这样import { native } from cc; export function unzip(zipPath: string, outPath: string): boolean { if (native.isNative) { return native.bridge.call(zipHelper, unzipToFolder, zipPath, outPath); } // Web端走JSZip逻辑 return unzipOnWeb(zipPath, outPath); }有几个细节我必须强调一下。第一unzReadCurrentFile的缓冲区大小我用的是8192字节这个值可以根据实际场景调整大文件可以放大到64KB解压速度会有明显提升。第二遍历条目时一定要判断unzGoToNextFile的返回值否则到zip包末尾时可能会出现意外行为。第三写文件时用wb模式不要用w否则在Windows平台上二进制数据会被截断。2.3 浏览器和小游戏端用JSZip兜底Web端和微信小游戏端没有原生文件系统我通常用JSZip来处理解压。JSZip的核心API是loadAsync传给它ArrayBuffer或Blob然后遍历文件列表逐个写入。小游戏端的代码大致如下import JSZip from jszip; export async function unzipOnMiniGame(arrayBuffer: ArrayBuffer, outDir: string): Promisevoid { const zip await JSZip.loadAsync(arrayBuffer); const fs wx.getFileSystemManager(); // 先确保根目录存在 fs.mkdirSync(outDir, true); for (const relativePath of Object.keys(zip.files)) { const entry zip.files[relativePath]; const fullPath outDir / relativePath; if (entry.dir) { fs.mkdirSync(fullPath, true); } else { // 确保父目录存在 const parentDir fullPath.substring(0, fullPath.lastIndexOf(/)); fs.mkdirSync(parentDir, true); const content await entry.async(uint8array); fs.writeFileSync(fullPath, content, binary); } } }这里要注意mkdirSync的第二个参数recursive在小游戏基础库低版本上可能不支持所以保险起见写文件前逐级创建父目录虽然多写几行代码但兼容性好很多。2.4 隐藏比较深的两个问题编码和内存第一个问题是中文文件名乱码。zip格式本身没有强制规定文件名编码Windows上压缩工具默认用GBKmacOS/Linux上大多用UTF-8。Cocos Creator在原生端拿到GBK编码的文件名时直接按UTF-8解析就会乱码。处理思路有两种一种是在压缩时就统一文件名编码团队内部约定使用UTF-8另一种是在解压时做编码判断和转换检测到非UTF-8时做编码转换。第一种方式成本最低但需要约束资源打包流程第二种方式兼容性更好适合解压来自外部系统的zip包。第二个问题是内存。JSZip在解压大文件时会把整个文件内容读取到内存中如果zip里放的是一个100MB的资源包内存峰值会非常吓人。原生minizip按块读取就没有这个问题。所以我的建议是大文件场景别用JSZip或者把zip里的资源按子目录拆分一次只解压需要的那一部分。3. 反过来生成zip与加密打包、密码与安全边界解压只解决了一半问题实际项目中经常还需要“把资源打包成zip”。比如导出存档、制作离线资源包、服务器端生成热更包这些都要用到zip的“写”能力。3.1 用minizip把游戏资源打包成zipminizip创建zip包的核心流程是打开zip文件逐个添加条目把数据写入最后关闭。下面是一段简化的打包代码bool ZipHelper::zipFolder(const std::string srcPath, const std::string zipPath, int compressLevel) { zipFile zip zipOpen(zipPath.c_str(), APPEND_STATUS_CREATE); if (!zip) return false; // 递归遍历srcPath下的所有文件逐个添加进zip for (const auto entry : std::filesystem::recursive_directory_iterator(srcPath)) { if (entry.is_directory()) { continue; } std::string fullPath entry.path().string(); // 计算相对路径作为zip内的条目名 std::string relativePath std::filesystem::relative(entry.path(), srcPath).string(); std::replace(relativePath.begin(), relativePath.end(), \\, /); // 读取文件内容并写入zip FILE* file fopen(fullPath.c_str(), rb); fseek(file, 0, SEEK_END); long fileSize ftell(file); fseek(file, 0, SEEK_SET); char* buffer new char[fileSize]; fread(buffer, 1, fileSize, file); fclose(file); zipOpenNewFileInZip(zip, relativePath.c_str(), nullptr, nullptr, 0, nullptr, 0, created by game client, Z_DEFLATED, compressLevel); zipWriteInFileInZip(zip, buffer, fileSize); zipCloseFileInZip(zip); delete[] buffer; } zipClose(zip, created by game client); return true; }打包时有一个容易忽略的细节zip内的条目名要统一使用正斜杠/不要用反斜杠\。Cocos Creator在加载zip内的资源时对路径分隔符的处理是敏感的Windows路径风格在Android和iOS上会引发“文件找不到”的问题。3.2 密码保护和AES加密设密前先想清楚zip本身支持设置密码minizip也提供了zipOpenNewFileInZip时传入密码参数的能力。但要注意传统的zip密码加密方式是ZipCrypto安全性较弱而且在一些解压工具上无法直接打开。minizip的AES扩展如aes-xamarin、aescrypt能提供更可靠的加密但兼容性需要额外验证。我个人的建议是如果zip只是防止“误打开”用传统密码就够了如果资源本身需要严格保密不要把安全寄托在zip密码上应该在业务层做加密处理。比如对zip包内的敏感资源先做AES加密再打包成zip解压后还要在代码里解密这样才能保证资源在没有密码的情况下不会被直接提取。3.3 压缩级别怎么选别拿游戏耗电开玩笑minizip的Z_DEFLATED压缩级别是0到90是不压缩9是最高压缩。很多新手喜欢直接用9觉得压缩率越高越好实际上在移动端会带来明显的CPU占用。压缩级别每提高1级CPU耗时可能增加20%到50%而体积节省可能只有几个百分点。我做热更包时实践下来觉得Z_DEFLATED配合6级压缩是一个比较均衡的状态体积不算大打包速度也扛得住。如果是纹理、音频这类本来就压缩过的文件压缩收益很小甚至可以直接用0级纯存储能大幅提升打包速度。4. 打包apk时zip的处理策略放包里还是放外部“cocos creator 打包apk”是搜索热度很高的话题很多问zip文件处理的其实是在纠结打包阶段zip放哪里。4.1 打进apk的zip与首次启动释放有些团队会把一个包含初始资源的zip放进apk的assets目录游戏首次启动时再解压到用户目录。这个做法的出发点是减少apk中的文件数量让安装包在文件系统上更整洁同时避免一些平台对大量小文件的IO性能损耗。关键坑在于assets目录在Android上是只读的不能直接在里面解压。正确做法是先把assets里的zip复制到getUserDataPath()对应的可写目录再执行解压。有同行图省事直接把assets路径传给解压函数结果解压失败排查了很久才发现是只读目录的问题。复制完成后还有一步很关键拷贝出来后经过解压assets里那份zip就没用了需要及时删除避免重复占用地盘。4.2 热更新目录下的zip落地与版本控制如果走热更新流程服务器下发的zip包建议统一放在一个独立目录并且以版本号命名。这样随时可以回到旧版本出问题也方便排查。我习惯在下载zip后先做两件事校验MD5再解压。校验在下载完成之后就做解压之前再校验一次写入磁盘的文件是否完整。这个习惯帮我挡住过不少次“下载到一半网络断了但文件大小刚好一致”的诡异问题。async function downloadAndApplyZip(url: string, version: string): Promisevoid { const zipPath path.join(native.getUserDataPath(), hotupdate, ${version}.zip); const outPath path.join(native.getUserDataPath(), hotupdate, unpacked_${version}); // 1. 下载zip await downloadFile(url, zipPath); // 2. 校验MD5 const remoteMd5 await getRemoteMd5(url .md5); const localMd5 computeFileMd5(zipPath); if (remoteMd5 ! localMd5) { throw new Error(zip md5 mismatch); } // 3. 解压 const ok unzip(zipPath, outPath); if (!ok) { throw new Error(unzip failed); } // 4. 加载解压后的bundle await assetManager.loadBundle(outPath /assets); }这段流程看似简单但每一步都可能出问题。比如MD5接口挂了比如解压到一半杀进程比如下一个版本的上一个版本还占着资源。所以热更zip的命名、路径、清理策略一定要在一开始就设计好否则越到后面越难受。4.3 别偷懒版本号与文件清单双管齐下依靠zip文件名做版本是不可靠的。包内的资源文件可能有增删而zip本身没有版本概念。我的经验是在zip包内额外放一个version.json记录当前资源的版本号、文件清单、MD5列表。解压时先读version.json再逐一比对文件是否存在、大小是否正确这样能最大程度避免“解压成功但加载失败”的情况。{ version: 1.0.12, files: { assets/bundle1/config.json: d41d8cd98f00b204e9800998ecf8427e, assets/bundle1/scene.scene: s3g2hk3h2k3h2k3h2k3, assets/bundle1/textures/hero.png: a1b2c3d4e5f6a7b8c9d0 } }校验清单的好处是一旦某个文件损坏可以精准定位到具体是哪个文件然后重新下载或修复而不是整个zip重新来一遍。5. 高频报错排查解压失败、文件找不到、中文乱码最后这部分我把自己和身边同事踩过的高频问题整理成一个排查清单希望对你有实际帮助。5.1 invalid zip archivecould not find eocd 的排查路径“invalid zip archive: could not find eocd”这个错误在导入资源包、加载zip、解压zip时都可能会出现。EOCD是zip文件末尾的中央目录结束标识报这个错说明文件尾部没有找到正确的zip结构。常见原因和排查路径如下文件不是真正的zip格式。很多网络上下载的“zip”其实是自解压格式或7z格式只是改了扩展名。用十六进制工具看一眼文件头部zip文件头是以PK开头的。下载不完整。文件传输过程中断导致zip文件末尾的EOCD缺失。重新下载并加上MD5校验。zip文件包含双重卷标或由特殊工具生成与解压库不兼容。尽量使用标准zip格式生成。Cocos Creator编辑器导入资源包时zip内文件路径过长或包含特殊字符导致编辑器解析失败。重新压缩保持文件名简洁。遇到这个错误第一步一定是确认文件完整性不要先怀疑代码。5.2 FileNotFoundException与copy失败常见原因Cocos Creator原生端报“FileNotFoundException”十有八九是路径问题。常见的几种情况目标目录不存在。解压前没有创建目录或者目录创建被系统拦截。检查getUserDataPath()返回的路径是否真的可写。相对路径和绝对路径混用。原生端建议一律使用绝对路径拼接目录用cc.path.join而不是手写字符串加号。小游戏端文件系统API不同。微信小游戏不能直接使用cc.sys.localStorage或原生文件API必须通过wx.getFileSystemManager()操作。Android上外置存储的权限问题。部分Android版本对外置SD卡写入有权限限制最好统一使用应用私有目录。5.3 GBK中文文件名乱码怎么治解压出来的文件名乱码我遇到的基本都是GBK编码问题。解决思路是在minizip解压时拿到文件名后不直接使用而是做一次编码转换。如果项目中的zip包全部由自己工具生成强烈建议统一为UTF-8文件名这是一劳永逸的办法。如果必须兼容外部系统打包的zip那么需要在解压环节增加编码识别逻辑先看zip包的flag位是否标记UTF-8如果没有标记且包含了非ASCII字符则按GBK解码。bool skipUtf8Check (fileInfo.flag 0x800) ! 0; if (!skipUtf8Check) { // 尝试将GBK转成UTF-8 std::string utf8Name convertGbkToUtf8(fileName); strcpy(fileName, utf8Name.c_str()); }5.4 问题速查表现象可能原因处理方式解压报invalid zip archive文件下载不完整或格式不对校验MD5、确保是标准zip格式解压后文件缺失zip内目录项与文件项顺序异常遍历时创建所有父目录Native端FileNotFoundException目标目录不存在解压前递归创建目录Web端解压内存暴涨大文件全部读入内存不用JSZip处理超大文件中文文件名乱码GBK/UTF-8编码不一致统一UTF-8或做编码转换推动apk后zip不存在写在只读目录assets里先复制到可写目录再操作下载的zip无法导入编辑器压缩工具生成了不兼容格式用标准zip避免自解压格式根据我的个人经验在Cocos Creator里处理和zip有关的需求最核心的还是“路径、编码、异步释放”这三件事。路径要统一规划编码要明确约定资源释放要及时。这三点做好了zip翻车的概率就会大幅下降。最后分享一个小技巧把zip的下载、校验、解压、加载这一整个流程封装成一个Promise链式函数内部处理所有平台差异和异常分支。项目里所有需要zip的场景复用这个函数既能少写很多重复代码遇到问题也只需要在一个地方修复比到处贴解压代码要省心得多。本文还有配套的精品资源点击获取