简介这份资源是面向 Laya 引擎开发者、微信小游戏项目组的微信小游戏分包模板针对发布时包体超过 4M 必须分包加载的场景提供可直接参考的工程结构与配置方案适合已掌握 Laya 基础、需要落地分包策略的中级开发者。压缩包共 7 个文件以 4 个 js 脚本和 2 个 json 配置为主另有 1 个 txt 说明文件js 承担主包与子包入口逻辑json 负责游戏与项目配置整体仅 3KB轻量易读便于快速对照自身项目改造。目前已有 376 人学习下载。读者可从中获取一套完整的分包目录组织方式理解主包与子包入口文件的划分思路并借助配置示例梳理微信小游戏分包加载的关键设置减少自行摸索成本为包体超限问题提供可复用的参考模板。1. 分包模板到底解决什么问题从一次主包超限的翻车说起小游戏平台对主包体积有硬性上限这个限制在项目早期几乎无感等到美术资源、音频、配置表陆续堆进来某天构建完一看主包超了。更麻烦的是超限不是构建报错而是上传阶段被拦或者真机上白屏、资源 404排查起来像开盲盒。wxgame_pack-分包模板.zip这类东西存在的意义就是把「哪些代码进主包、哪些资源进子包、加载顺序怎么排」这套规则提前固化成一套可复用的目录结构和构建配置而不是等到超限了再临时拆。它适合两类人一类是刚接手小游戏项目、还没经历过主包超限的开发者提前把分包骨架搭好另一类是老项目已经超了需要一套能照着改的拆分方案。核心要解决的就三件事——主包只留启动必需子包按功能或场景切分加载时机和失败兜底写清楚。下面按「先理解分包机制再动手搭模板最后排坑」的顺序讲中间会给可直接抄的目录结构和配置代码。2. 分包机制与模板选型主包、子包、独立分包怎么划2.1 主包与子包的加载时序差异小游戏的包体分三类主包、普通子包、独立分包。主包在启动时全量下载并执行普通子包要等主包执行完、调用加载接口后才下载独立分包则可以在不依赖主包的情况下单独启动。理解这个时序是拆分的前提——主包里放的是「不加载就起不来」的东西比如入口脚本、启动场景、基础框架、全局配置。子包里放的是「用到才加载」的东西比如某个玩法关卡、某个二级页面、某批皮肤资源。很多人拆包的误区是按文件类型拆把所有图片丢一个包、所有音频丢一个包。这样拆的问题是加载粒度太粗进一个玩法要把整个图片包拉下来。更合理的做法是按业务模块拆一个玩法模块的脚本、图片、配置放同一个子包加载时一次性拉齐用完可以释放。模板里通常会预留subpackages配置段和对应的目录约定就是让你按模块往里填。2.2 独立分包适合什么场景独立分包的价值在于「不启动主包也能跑」。典型场景是分享落地页、活动页、排行榜这类从外部直接进入的页面。用户点分享链接进来如果走主包启动要先把主包全部下载执行完才能进活动页首屏时间被主包体积拖累。用独立分包平台可以直接加载这个分包并启动跳过主包。但独立分包有约束它不能访问主包里的模块和全局变量只能用自己的代码和资源。所以模板里如果规划了独立分包目录通常会把公共依赖再复制一份进去或者把公共部分抽成更小的基础包。这个取舍要看活动页的复杂度简单页面直接独立复杂页面还是走普通子包更省事。2.3 模板目录结构怎么落地拿到一个分包模板第一步是看它的目录约定。常见结构是主包代码放src/子包按模块放src/subpackages/模块名/每个子包内部再分scripts/、assets/、config/。构建配置里用subpackages数组声明每个子包的root、name、independent字段。下面是一个可直接改的配置示例// game.json 中的分包配置小游戏平台通用字段 { subpackages: [ { name: levelA, // 子包名加载时用这个名字 root: subpackages/levelA/, // 子包根目录必须和实际路径一致 independent: false // 普通子包依赖主包 }, { name: activity, // 活动页子包 root: subpackages/activity/, independent: true // 独立分包不依赖主包 } ], mainPackage: { root: src/ // 主包根目录 } }这段配置的关键在root字段它必须和磁盘上的实际目录完全对应大小写、结尾斜杠都不能错。name是后续调用加载接口时用的标识建议用英文短名别用中文或特殊字符。independent为 true 时平台会校验这个子包有没有引用主包内容引用了会直接报错。改完配置后构建产物里会按这个结构生成对应的包文件上传时平台按包分别校验体积。2.4 主包体积的预算怎么定拆包之前先算一笔账平台主包上限假设是 4MB不同平台数值不同以实际为准你要留出至少 20% 余量给后续迭代那主包实际控制在 3.2MB 以内。把主包内容列出来——引擎运行时、启动脚本、首场景、基础 UI 框架、全局配置表逐项估体积。如果引擎运行时本身就占了大头那主包能塞的业务代码就非常有限几乎所有玩法都得进子包。模板里一般会带一个体积分析脚本构建后输出各包体积明细。没有的话自己加一个在构建完成回调里读产物目录按文件类型汇总。这个脚本是后续每次迭代的体检工具别省。3. 照着模板搭一套可运行的分包骨架3.1 从模板复制到项目后的第一步改造模板解压后通常是一个最小可运行示例直接跑能起来但里面的模块名、路径都是占位。第一步是把subpackages配置里的示例子包改成你项目真实的模块划分。假设你有「主城」「战斗」「背包」三个模块主城放主包战斗和背包各做一个子包。改配置{ subpackages: [ { name: battle, root: subpackages/battle/, independent: false }, { name: bag, root: subpackages/bag/, independent: false } ], mainPackage: { root: src/ } }然后建目录src/下放主城代码和入口subpackages/battle/和subpackages/bag/下各放自己的脚本和资源。注意子包目录里不要再出现src/这一层root指向哪代码就从哪开始算路径。改完跑一次构建看产物里有没有生成对应的子包文件没有的话检查root路径和实际目录是否一致。3.2 子包加载接口的调用与错误处理普通子包加载用平台提供的接口通常是loadSubpackage这类方法传入子包名和回调。下面是一个带重试和降级的封装// 封装子包加载带一次重试和失败提示 function loadSubpackageWithRetry(name, retryCount 1) { return new Promise((resolve, reject) { const attempt (left) { const task wx.loadSubpackage({ name: name, // 对应配置里的 name 字段 success: () resolve(name), fail: (err) { if (left 0) { // 还有重试次数延迟 500ms 再试 setTimeout(() attempt(left - 1), 500); } else { reject(new Error(子包 ${name} 加载失败: ${err.errMsg})); } } }); // 可选监听加载进度用于显示进度条 task.onProgressUpdate((res) { console.log(${name} 加载进度: ${res.progress}%); }); }; attempt(retryCount); }); }这段代码里name必须和game.json里的name完全一致不一致会直接 fail。retryCount建议设 1网络抖动重试一次足够重试太多会让用户等太久。onProgressUpdate拿到的progress是 0 到 100 的整数可以驱动一个进度条 UI。失败时的errMsg要打到日志里常见的是「子包不存在」或「网络错误」前者查配置后者查网络。3.3 资源引用路径在分包后的变化拆包后最容易翻车的是资源路径。原来在主包里用相对路径引用的图片挪到子包后相对路径的基准变了会 404。模板里一般会约定一套路径别名比如用battle/指代战斗子包根目录构建时替换成实际路径。如果没有别名机制就老老实实按子包根目录写绝对路径。另一个坑是主包代码引用子包资源。主包执行时子包还没下载这时候去引用子包里的图片必然失败。正确做法是主包只引用主包资源子包资源在子包加载完成后由子包自己的代码引用。如果主包确实需要用到某个子包的资源要么把它挪回主包要么改成运行时动态加载。3.4 构建脚本里要加的体积校验模板自带的构建流程通常只负责打包不负责校验。建议在构建完成回调里加一段体积检查超过阈值就报错中断避免超限的包被传到平台才发现。下面是一个简单的校验脚本// 构建后校验各包体积超过阈值则抛错 const fs require(fs); const path require(path); const LIMITS { main: 3.2 * 1024 * 1024, // 主包上限 3.2MB battle: 2 * 1024 * 1024, // 战斗子包上限 2MB bag: 1 * 1024 * 1024 // 背包子包上限 1MB }; function checkSize(pkgName, dir) { let total 0; const walk (d) { fs.readdirSync(d).forEach((f) { const full path.join(d, f); const stat fs.statSync(full); if (stat.isDirectory()) walk(full); else total stat.size; }); }; walk(dir); const limit LIMITS[pkgName]; if (limit total limit) { throw new Error(${pkgName} 体积 ${(total/1024/1024).toFixed(2)}MB 超过上限 ${(limit/1024/1024).toFixed(2)}MB); } console.log(${pkgName}: ${(total/1024/1024).toFixed(2)}MB); } checkSize(main, dist/src); checkSize(battle, dist/subpackages/battle); checkSize(bag, dist/subpackages/bag);LIMITS里的数值按你平台的实际上限和预留余量来定别照抄。walk递归累加文件大小目录本身不计。这个脚本挂在构建命令后面超限直接让 CI 失败比人工检查靠谱。4. 分包落地时最容易踩的五个坑4.1 子包配置了但加载时报「不存在」现象是调用加载接口返回 failerrMsg 提示子包不存在。原因通常是game.json里的root路径和实际构建产物目录对不上比如配置写subpackages/battle/但构建输出到了dist/subpackages/battle/中间少了一层。解决方法是打开构建产物目录逐级核对路径确保root是相对于主包根目录的路径不是相对于项目根目录。4.2 独立分包里引用了主包模块导致构建失败现象是构建时报错提示独立分包不能引用主包内容。原因是独立分包设计上就不依赖主包代码里如果require了主包的模块平台校验会拦。解决方法是把被引用的公共代码抽到一个更基础的包里或者直接复制一份到独立分包目录内。复制会增大体积但独立分包本来就不该太大权衡着来。4.3 子包加载完成后资源仍然 404现象是加载接口 success 了但子包里的图片加载失败。原因多半是资源路径写的是相对路径而运行时的当前路径和预期不一致。解决方法是统一用子包根目录的绝对路径引用或者在子包入口处把当前路径切到子包根目录。模板里如果有路径别名机制优先用别名构建时替换运行时就不会有歧义。4.4 主包体积降不下来拆完还是超现象是拆了子包主包体积没怎么变。原因是主包里还留着大量可以挪走的资源比如首场景用不到的高清图、没压缩的音频。解决方法是先用体积分析脚本列出主包内体积最大的十个文件逐个判断能不能挪到子包或压缩。常见的大头是未压缩的 PNG 和 WAV转成压缩格式能省一半以上。4.5 子包加载时机太晚导致卡顿现象是进入某个玩法时先黑屏或卡住然后才加载出来。原因是子包加载放在了进入玩法的瞬间用户要等下载。解决方法是在上一个场景的空闲时间预加载下一个可能用到的子包比如主城加载完成后后台预加载战斗子包。预加载要注意别和当前场景抢带宽可以延迟几百毫秒再启动。5. 进阶用预加载和按需释放把分包体验做顺分包搭起来只是及格线体验好不好看的是加载时机。我一般会在主城场景的onLoad完成后延迟 1 秒启动战斗子包的预加载用户点进战斗时子包已经就绪感知不到等待。预加载的代码和普通加载一样只是不阻塞当前流程// 主城加载完成后空闲时预加载战斗子包 setTimeout(() { loadSubpackageWithRetry(battle).then(() { console.log(战斗子包预加载完成); }).catch((err) { // 预加载失败不打扰用户等真正进入时再加载一次 console.warn(预加载失败进入时重试, err); }); }, 1000);延迟 1 秒是为了避开主城首屏渲染的资源竞争具体数值可以按项目调。预加载失败不要弹提示静默记录等用户真正进入战斗时再走一次加载流程那时候失败才需要提示。另一个进阶点是子包释放。小游戏平台一般提供释放子包内存的接口退出某个玩法后可以把对应子包释放掉给后续玩法腾空间。释放的时机要选在确认不会再回到该玩法的场景切换点释放后如果用户又回来需要重新加载。这个取舍看玩法之间的跳转频率高频互跳的玩法之间不释放低频的可以释放。验证分包是否生效除了看构建产物还要在真机上跑。开发者工具里的包体分析和真机有时不一致尤其是独立分包的行为。真机验证时重点看三件事主包启动时间、子包首次加载耗时、子包加载失败率。这三个指标正常分包方案才算落地。我自己踩得最深的一次是独立分包的路径问题配置里root写对了但构建脚本里有个步骤把独立分包的产物又拷回了主包目录导致平台校验时认为独立分包引用了主包卡了两天才定位到。从那以后我养成的习惯是每次改完分包配置先跑构建再手动打开产物目录逐级核对路径最后真机跑一遍加载流程三步缺一不可。希望帮到你。本文还有配套的精品资源点击获取