做了几年小游戏我最深的体会是最贵的成本从来不是写业务代码而是第一次把包塞进真机里跑起来的那两天。一个空工程从点击构建到手机上亮起画面中间要跨过平台切换、包体限制、内存上限、音频解锁、分包加载这一串关卡每一关都能让人卡半天。这篇就从一个完全空白的工程开始讲清楚用团结引擎搭建第一个微信小游戏的完整路径以及我整理的那套 Starter Kit 里到底该放什么。适合两类人看一类是熟悉引擎但没碰过小游戏这条链路的另一类是刚开始做小游戏、被包体或者黑屏折磨过的。我不会只给操作步骤每个参数为什么这么设、这个坑为什么会踩都会讲明白。1. 选题背后的真实取舍为什么是这套组合1.1 三个绕不开的选型问题动手之前先把选型想清楚比后面调参数省事得多。第一个问题是引擎要不要换。已经熟悉某个引擎的团队换个引擎重学的成本往往被低估而团结引擎和主流引擎在编辑器操作、C# 脚本、组件体系上高度接近老项目迁移过来的心理成本很低这是它最实际的优势。第二个问题是渲染能力够不够。小游戏跑在手机浏览器的图形环境里本质是那一套 Web 图形接口性能天花板比原生低一截指望在小游戏上做重度的实时光影、大世界流式加载那是给自己找麻烦。第三个问题是发布链路顺不顺。有些方案需要自己写一层平台适配构建产物还要手工改配置团结引擎这边把微信小游戏的构建目标做进了编辑器里切平台、填 AppID、出包流程是一条线走下来的。这三件事想清楚了后面的技术决策基本就自动确定了。如果你要做的是休闲玩法、轻中度数值、玩法循环在 3 分钟以内的东西这套组合非常合适如果你要做的是重度的 3D 动作游戏那在动手前就该认真评估一下降级方案比如砍掉实时光影、把材质退回简单光照模型。1.2 这条链路能做什么、做不到什么很多人对小游戏的误解在于把它当成了手机上跑的 PC 游戏缩小版。实际情况是它更像跑在微信环境里的一个网页应用只是这个网页应用带了一套完整的渲染和脚本运行时。理解这个定位很多限制就顺理成章了。能力维度实际表现常见误区渲染支持 PBR、后处理、粒子但要按性能预算砍以为能直接搬 PC 效果包体主包有明确的体积硬限制全量包也有上限以为可以无限加资源内存低端安卓机可用余量有限几百 MB 量级以为手机内存大就随便用音频首次播放需要用户交互触发解锁以为进游戏就能放 BGM存储本地存储有容量上限跨版本要注意清理以为能当数据库用网络走 HTTPS域名需要在平台侧配置白名单以为随便请求表里这几条我见过太多团队在开发两周后才撞上。尤其是域名白名单和音频解锁前者会导致真机上接口全挂、本机开发却一切正常后者会导致进游戏没声音这个经典问题反复出现在测试反馈里。提示包体和内存的具体数值平台会不定期调整动手前一定去查当天的最新文档别拿半年前的博客当标准。1.3 Starter Kit 该装进哪些东西所谓 Starter Kit本质是把每个项目都要重写一遍、且每次都写得不太一样的那部分代码抽出来做成一个能直接复制粘贴的底座。我整理过的版本大概包含五块内容缺一块都会在后面某个环节被卡住。第一块是启动流程骨架包括一个极简的 Loading 场景和一个状态机负责控制初始化平台 → 检查资源版本 → 加载主场景这个顺序。第二块是平台能力抽象层把登录、震动、分享、广告、存储这些平台 API 包一层接口业务层只依赖接口不直接调平台 SDK。第三块是资源与分包管理负责主包内资源和分包资源的加载调度。第四块是通用 UI 框架包括弹窗栈、Toast、加载遮罩这类高频组件。第五块是构建脚本把重复的构建设置固化成代码避免每次出包都要手工点十几项设置。这五块东西加起来不到两千行代码但它决定了你后面是每天都能出包还是每次出包都要折腾两小时。2. 环境搭建与工程初始化2.1 版本与工具链的确定环境这块我建议把版本锁死写进项目文档里任何人不许私自升级。引擎版本、平台构建模块、开发者工具的版本这三个要成套匹配混着用很容易出现构建成功但真机白屏这类查不出原因的问题。工具链的顺序大概是这样的先装引擎管理工具用它在本地装一个确定版本的编辑器安装时勾选微信小游戏的构建支持模块不同版本里这个模块的命名可能略有差别装的时候看清楚是不是和小游戏发布相关的那一项然后装平台侧的开发者工具用来导入构建产物、预览和真机调试最后准备一个测试用的 AppID没有正式的最好也申请一个测试的因为某些接口在不填 AppID 的情况下行为不一致。这里有个特别容易忽略的点开发者工具里的调试基础库版本。它相当于运行时的固件版本版本太旧会不支持新接口版本太新又可能和你引擎侧的适配层对不上。我的做法是固定一个经过验证的版本在项目 README 里写死团队所有人统一。2.2 新建工程到平台切换新建工程的时候模板选最干净的那个就行别一上来就选带一堆示例资源的模板那些资源后面全要清理而且会污染你对首包体积的判断。工程建好后先做三件事把项目名、包名、公司名这些基础信息填对包名后面改起来麻烦把色彩空间、图形 API 这些基础设置定下来然后立刻切平台。切平台这一步切完之后重新打开构建设置面板确认平台确实切过去了。我吃过一次教训点了切换编辑器在后台编译我以为切完了直接点构建结果出来的是另一个平台的包白等二十分钟。切过去之后面板里会出现跟小游戏相关的配置项最关键是 AppID 和资源压缩方式。AppID 填错的表现是构建能过、导入开发者工具报错压缩方式选错的表现是包更大或者加载更慢。压缩这块我一般选平台支持得最好的那种具体哪一项要看当前版本的支持矩阵选之前确认一下目标机型的兼容性。2.3 第一次构建先让空包在真机亮起来我在带人的时候有个硬性要求第一个里程碑不是功能跑通而是空包在真机上亮起来。这个顺序不能反因为只有把链路打通了后面所有问题才能区分是业务代码的问题还是环境的问题。具体做法是新建一个空场景场景里只放一个相机和一块纯色背景加一个显示帧率的文本然后直接构建。构建产物的目录结构大概是这个样子Build/wxminigame/ ├── index.html ├── game.js ├── game.json ├── unity.framework.js ├── unity.wasm.br └── data/不同版本的产物命名会有些差别但核心就这几样一个入口脚本、一个引擎运行时、一个编译出来的二进制、一个资源数据包。用开发者工具选择导入项目项目类型选小游戏目录指到构建产物的根目录导入后点编译如果模拟器里能看到那块纯色背景说明链路通了。真机验证这一步千万别省。模拟器和真机之间的差异大得离谱模拟器跑 60 帧的东西真机上可能只有 20 帧模拟器能正常播放的音频真机上没声音模拟器里内存充裕真机上一加载就崩。第一次就扫码上真机把能亮起来这件事确认死后面才有底气。注意真机预览的二维码有时效过期了重新生成就行不要以为是构建失败。3. Starter Kit 的骨架拆解3.1 目录结构与分层底座工程的目录结构我倾向于按职责分而不是按类型分。按类型分Scripts、Prefabs、Materials 这样在项目小的时候很清爽一旦超过两万行就开始混乱。按职责分的结构大概是这样Assets/ ├── _Project/ │ ├── Boot/ 启动场景与初始化脚本 │ ├── Core/ 状态机、事件总线、对象池 │ ├── Platform/ 平台能力抽象与实现 │ ├── Res/ 资源加载与分包调度 │ ├── UI/ 通用 UI 框架 │ └── Game/ 业务玩法 ├── _Art/ 美术资源按模块再分 └── _ThirdParty/ 第三方库隔离起来下划线前缀的作用是把这些目录顶到最前面视觉上和引擎自带目录分开。Platform这一层是重点它里面放的是接口定义和平台实现业务层只引用接口。这样一来如果哪天要出别的平台版本只需要再写一份实现业务代码一行不动。3.2 启动流程与状态机启动流程千万不要用一堆协程互相调用那样出了问题根本查不出来。用一个显式的状态机每个状态负责一件事状态之间通过明确的推进条件串联。public enum BootState { None, InitPlatform, // 平台 SDK 初始化 CheckVersion, // 资源版本检查 LoadMain, // 加载主场景 Ready } public class BootFlow : MonoBehaviour { private BootState _state BootState.None; private void Start() Enter(BootState.InitPlatform); private void Enter(BootState next) { _state next; Debug.Log($[Boot] - {next}); switch (next) { case BootState.InitPlatform: PlatformBridge.Instance.Init(ok { if (!ok) { ShowRetry(初始化失败); return; } Enter(BootState.CheckVersion); }); break; case BootState.CheckVersion: ResManager.Instance.CheckUpdate(p { SetProgress(p); }, ok Enter(ok ? BootState.LoadMain : BootState.None)); break; case BootState.LoadMain: ResManager.Instance.LoadScene(Main, () Enter(BootState.Ready)); break; } } }这段代码的价值不在于它多精妙而在于它把启动这个黑盒变成了四个可以独立打日志、独立重试的环节。用户卡在哪个环节日志里一眼就能看出来。我在实际项目里靠这个结构定位过至少五六次线上问题比如某次是平台初始化回调在某些机型上延迟特别久从日志的时间戳上一秒就能确认。3.3 平台能力抽象层平台 API 直接散落在业务代码里是后期维护的灾难。抽象层的写法不复杂核心是定义一个接口然后写一个实现类把平台 SDK 包起来。public interface IPlatformBridge { void Init(Actionbool onDone); void Login(Actionstring onCode, Actionstring onFail); void VibrateShort(); void Share(string title, string imageUrl); void ShowRewardAd(string adUnitId, Actionbool onResult); } public class WXBridge : IPlatformBridge { public void Init(Actionbool onDone) { WX.InitSDK(code { Debug.Log($[WX] init code{code}); onDone(code 0); }); } public void Login(Actionstring onCode, Actionstring onFail) { WX.Login(new LoginOption { success res onCode?.Invoke(res.code), fail err onFail?.Invoke(err.errMsg) }); } public void VibrateShort() WX.VibrateShort(new VibrateShortOption { type light }); public void Share(string title, string imageUrl) { WX.ShareAppMessage(new ShareAppMessageOption { title title, imageUrl imageUrl }); } public void ShowRewardAd(string adUnitId, Actionbool onResult) { var ad WX.CreateRewardedVideoAd(new WXCreateRewardedVideoAdParam { adUnitId adUnitId }); ad.OnClose(res onResult?.Invoke(res.isEnded)); ad.Show(); } }命名空间和类名在不同版本的 SDK 里会有出入上面这段按你本地实际类型名调整即可思路是一样的。要点有三个第一所有平台回调都要在回调里做异常保护平台回调抛异常有时候会直接把整个运行时打崩第二广告这类有实例生命周期的能力实例要缓存复用别每次展示都新建一个第三接口要设计成失败也有回调否则业务层会写出永远等不到结果的代码。3.4 资源与分包策略资源这块的核心矛盾是美术想要高精度包体不允许。解决方向只有两个一是把资源压缩到极致二是把资源挪出主包。主包里只放启动必需的资源Loading 图、字体、一个极简的主菜单。剩下的全部进分包。分包的划分粒度建议按玩法模块切不要按资源类型切因为按类型切所有图一个包、所有音效一个包会导致加载一个关卡要拉好几个包首次进入的等待时间长到用户直接退出。public void LoadSub(string pkgName, Action onDone, Actionstring onFail) { WX.LoadSubpackage(new LoadSubpackageOption { name pkgName, success _ { Debug.Log($[Res] subpackage {pkgName} ready); onDone?.Invoke(); }, fail e { Debug.LogError($[Res] {pkgName} fail: {e.errMsg}); onFail?.Invoke(e.errMsg); } }); }分包加载是异步的而且同一时间加载多个包可能互相拖慢所以调度层要做一个队列按优先级串行推进。我在一个项目里试过同时加载三个包结果是总耗时比串行还长因为网络请求互相抢占带宽。4. 核心环节实操把包体、内存、帧率摁住4.1 首包瘦身的六个动作首包体积是第一个绕不过去的硬指标。主包有明确的体积上限超了直接构建失败或者真机加载失败。我一般按下面这个顺序做瘦身从收益最大的开始。动作一引擎模块裁剪。在项目设置里把用不到的模块关掉物理、地形、视频播放、粒子系统的某些高级特性这些每个都占几百 KB。关之前确认一下依赖有些模块关掉会导致第三方插件编译不过。我见过一个项目因为用了某个 UI 插件被迫保留了一整套物理模块白占了一兆多。动作二代码裁剪等级拉到最高。托管代码裁剪等级提上去能砍掉大量没被引用的库代码。风险是反射调用的代码会被误删所以要配一份保留清单把通过字符串反射访问的类型写进去。动作三资源压缩格式统一。贴图按平台支持的最优格式压缩关掉用不到的 mipmap关掉读写权限。音频统一成小体积格式长音乐设成流式加载短音效设成压缩进内存。动作四剔除重复资源。这个最容易被忽略。同一个图集被打进两个不同的资源包体积就翻倍。定期跑一遍资源依赖分析把重复的合并掉。动作五字体裁剪。中文字体动辄几兆一定要做子集化只保留实际用到的字符。这一项经常能省下两三兆。动作六关闭无用的日志和调试符号。出正式包的时候把调试符号剥离日志级别调高这一项对体积影响不大但对加载速度有影响。做完这六项一个中等规模的 2D 项目主包控制在体积上限的一半以内是现实的。留一半余量是有必要的因为后面一定会不断往里塞东西。4.2 内存与帧率低端机才是真考场内存这块我建议直接拿一台三五年前的低端安卓机当基准设备所有性能验收都在这台机器上做。高端机上跑得飞起的项目在它上面可能连主菜单都进不去。首先要搞清楚内存花在哪。贴图通常是大头尤其是那些尺寸没控制好的 UI 图。一张 2048×2048 的不带压缩的图显存占用就是十几兆几十张这样的图叠起来低端机直接崩。解决办法就是严格控制尺寸和压缩格式UI 图能用 512 就别用 1024能用图集合并就别散着放。其次是托管堆。C# 的垃圾回收在小游戏的运行环境里开销比原生大频繁分配会产生明显的卡顿。做法很朴素热路径上不要 new字符串拼接改成缓存的构建器列表和字典提前预分配容量对象池该用就用。这些是老生常谈但真正做的时候代码里随手 new 的地方永远比你以为的多。// 反例每帧都在产生垃圾 void Update() { scoreText.text 得分 score / total; } // 改法只在数据变化时更新且用缓存 private int _lastScore -1; void Update() { if (score _lastScore) return; _lastScore score; _sb.Clear(); _sb.Append(得分).Append(score).Append( / ).Append(total); scoreText.text _sb.ToString(); }帧率方面先想清楚目标。动作类、需要跟手的玩法冲 60 帧休闲益智类锁 30 帧完全够用而且省电省发热用户体验反而更好。锁帧的做法是设置目标帧率并关掉垂直同步让引擎按你的节奏走。Draw Call 是另一个常见瓶颈。UI 层面靠图集合并解决确保同一个界面里的元素尽量来自同一张图集并且层级顺序上不要交叉。场景层面靠静态合批和材质共享同一种材质的物件尽量复用。4.3 真机调试与日志真机调试体验做得好不好直接决定排查效率。我的做法是在底座里内置一个简单的日志面板把关键日志同时输出到控制台和这个面板上真机上可以点开看。日志分级别正式的包里只保留警告和错误开发包全开。日志里一定要带时间戳和状态标记比如[Boot]、[Res]、[Net]这样的前缀出问题的时候按前缀过滤一眼就能看出是哪个环节挂了。还有一个实用技巧在启动流程的每个状态切换点记录一次时间戳最后打出一条汇总。这样一眼就能看出这个用户卡在资源检查花了 8 秒比翻几百行日志快得多。5. 常见问题排查实录5.1 构建与导入阶段的问题构建阶段最常见的问题是构建失败但报错信息极其含糊。这时候先看两件事平台是不是真的切过去了AppID 是不是填了。这两个是最基础也最容易被忽略的。导入开发者工具报错先看项目类型选对没有。选成小程序而不是小游戏表现是一堆文件识别不了。再看目录指对没有必须指到构建产物的根目录指到上一级或者下一级都会出问题。编译报包体积超限那就回到上一节的瘦身流程。这里有个坑有时候你删了资源但构建缓存里还留着旧的包体积下不来。清一次构建缓存重新出包往往能省下一大截。真机扫码后白屏这个最折磨人。排查顺序建议这样先在开发者工具里打开调试控制台看有没有报错如果没有报错但就是白屏检查首场景是不是在构建列表里且索引为 0如果场景没问题检查首场景里是不是有个能正常工作的相机和背景色。我遇到过一次是背景色设成了完全透明看起来就是白屏查了两个小时。5.2 运行期的问题运行期问题的表现形式五花八门但根源往往集中在几个地方。音频没声音九成是解锁问题。平台的音频策略要求首次播放由用户交互触发所以在启动流程里加一个点击开始的按钮在按钮回调里播一段静音或者极短的音频把通道打开后面的 BGM 就正常了。真机掉帧严重但模拟器流畅先看分辨率。有些项目在真机上跑的是设备全分辨率像素量是模拟器的好几倍。把渲染分辨率按设备能力做分级低端机降一档帧率立刻就上来了。接口请求失败但本机开发正常去查域名白名单。这个配置在平台侧不在代码里所以本机跑通了不代表真机能跑通。本地存储读不到检查是不是跨版本了。存储有容量上限写满了会静默失败读的时候拿到空值。做法是每次写入前先估算剩余空间超了就先清理旧数据。5.3 排查速查表现象最可能原因优先验证方式构建失败平台未切换 / AppID 未填看构建设置面板状态导入报错项目类型选错重新导入并选小游戏包体超限缓存未清 / 资源重复清缓存后重新构建对比真机白屏首场景配置 / 相机设置检查构建列表与场景内容无音频未做交互解锁加点击回调后重测掉帧渲染分辨率过高降档分辨率对比帧率接口失败域名白名单未配平台侧配置核对存储失效容量写满检查写入返回值内存崩溃贴图尺寸超标逐张排查大图提示这张表建议打印出来贴在工位上出问题的时候先照表过一遍能省下大量瞎猜的时间。6. 底座之上还能长出什么底座搭好之后接下来的扩展方向其实挺多的。我个人最推荐先做的是数据埋点因为小游戏的调优极度依赖真实数据哪个环节流失、哪一步加载慢光靠猜是不行的。埋点不用做得很重启动耗时、场景切换耗时、关键按钮点击、异常上报这四类数据足够支撑早期的决策了。第二个方向是自动化构建。把构建脚本挂到持续集成的流水线上每次提交自动出一个包传到内部分发渠道。这件事前期投入一两天后期每次发版省下的时间和避免的人为失误回报非常高。第三个方向是多平台兼容。抽象层如果一开始就设计对了后面接别的平台就是再写一份实现的事。我建议在底座里保留一个编辑器模拟实现让业务开发在编辑器里就能跑通完整流程不用每次都上真机这个开发效率的提升是很明显的。最后分享一个我个人踩过好几次的坑底座代码本身也要有版本管理而且要和业务工程分离。我见过太多团队把底座代码直接复制到每个项目里改了一份忘了另一份最后三四个项目的行为各不相同出了问题都不知道以哪份为准。把底座做成一个可以按版本引入的包这个习惯越早养成越好。帧率调优那部分我还想补一句别迷信 60 帧。有些休闲玩法锁 30 帧之后手机发热明显降低长时间玩下来体验反而更稳。这一点在小游戏这种随时打开随时关的场景里比多那 30 帧重要得多。
做了几年小游戏我最深的体会是最贵的成本从来不是写业务代码而是第一次把包塞进真机里跑起来的那两天。一个空工程从点击构建到手机上亮起画面中间要跨过平台切换、包体限制、内存上限、音频解锁、分包加载这一串关卡每一关都能让人卡半天。这篇就从一个完全空白的工程开始讲清楚用团结引擎搭建第一个微信小游戏的完整路径以及我整理的那套 Starter Kit 里到底该放什么。适合两类人看一类是熟悉引擎但没碰过小游戏这条链路的另一类是刚开始做小游戏、被包体或者黑屏折磨过的。我不会只给操作步骤每个参数为什么这么设、这个坑为什么会踩都会讲明白。1. 选题背后的真实取舍为什么是这套组合1.1 三个绕不开的选型问题动手之前先把选型想清楚比后面调参数省事得多。第一个问题是引擎要不要换。已经熟悉某个引擎的团队换个引擎重学的成本往往被低估而团结引擎和主流引擎在编辑器操作、C# 脚本、组件体系上高度接近老项目迁移过来的心理成本很低这是它最实际的优势。第二个问题是渲染能力够不够。小游戏跑在手机浏览器的图形环境里本质是那一套 Web 图形接口性能天花板比原生低一截指望在小游戏上做重度的实时光影、大世界流式加载那是给自己找麻烦。第三个问题是发布链路顺不顺。有些方案需要自己写一层平台适配构建产物还要手工改配置团结引擎这边把微信小游戏的构建目标做进了编辑器里切平台、填 AppID、出包流程是一条线走下来的。这三件事想清楚了后面的技术决策基本就自动确定了。如果你要做的是休闲玩法、轻中度数值、玩法循环在 3 分钟以内的东西这套组合非常合适如果你要做的是重度的 3D 动作游戏那在动手前就该认真评估一下降级方案比如砍掉实时光影、把材质退回简单光照模型。1.2 这条链路能做什么、做不到什么很多人对小游戏的误解在于把它当成了手机上跑的 PC 游戏缩小版。实际情况是它更像跑在微信环境里的一个网页应用只是这个网页应用带了一套完整的渲染和脚本运行时。理解这个定位很多限制就顺理成章了。能力维度实际表现常见误区渲染支持 PBR、后处理、粒子但要按性能预算砍以为能直接搬 PC 效果包体主包有明确的体积硬限制全量包也有上限以为可以无限加资源内存低端安卓机可用余量有限几百 MB 量级以为手机内存大就随便用音频首次播放需要用户交互触发解锁以为进游戏就能放 BGM存储本地存储有容量上限跨版本要注意清理以为能当数据库用网络走 HTTPS域名需要在平台侧配置白名单以为随便请求表里这几条我见过太多团队在开发两周后才撞上。尤其是域名白名单和音频解锁前者会导致真机上接口全挂、本机开发却一切正常后者会导致进游戏没声音这个经典问题反复出现在测试反馈里。提示包体和内存的具体数值平台会不定期调整动手前一定去查当天的最新文档别拿半年前的博客当标准。1.3 Starter Kit 该装进哪些东西所谓 Starter Kit本质是把每个项目都要重写一遍、且每次都写得不太一样的那部分代码抽出来做成一个能直接复制粘贴的底座。我整理过的版本大概包含五块内容缺一块都会在后面某个环节被卡住。第一块是启动流程骨架包括一个极简的 Loading 场景和一个状态机负责控制初始化平台 → 检查资源版本 → 加载主场景这个顺序。第二块是平台能力抽象层把登录、震动、分享、广告、存储这些平台 API 包一层接口业务层只依赖接口不直接调平台 SDK。第三块是资源与分包管理负责主包内资源和分包资源的加载调度。第四块是通用 UI 框架包括弹窗栈、Toast、加载遮罩这类高频组件。第五块是构建脚本把重复的构建设置固化成代码避免每次出包都要手工点十几项设置。这五块东西加起来不到两千行代码但它决定了你后面是每天都能出包还是每次出包都要折腾两小时。2. 环境搭建与工程初始化2.1 版本与工具链的确定环境这块我建议把版本锁死写进项目文档里任何人不许私自升级。引擎版本、平台构建模块、开发者工具的版本这三个要成套匹配混着用很容易出现构建成功但真机白屏这类查不出原因的问题。工具链的顺序大概是这样的先装引擎管理工具用它在本地装一个确定版本的编辑器安装时勾选微信小游戏的构建支持模块不同版本里这个模块的命名可能略有差别装的时候看清楚是不是和小游戏发布相关的那一项然后装平台侧的开发者工具用来导入构建产物、预览和真机调试最后准备一个测试用的 AppID没有正式的最好也申请一个测试的因为某些接口在不填 AppID 的情况下行为不一致。这里有个特别容易忽略的点开发者工具里的调试基础库版本。它相当于运行时的固件版本版本太旧会不支持新接口版本太新又可能和你引擎侧的适配层对不上。我的做法是固定一个经过验证的版本在项目 README 里写死团队所有人统一。2.2 新建工程到平台切换新建工程的时候模板选最干净的那个就行别一上来就选带一堆示例资源的模板那些资源后面全要清理而且会污染你对首包体积的判断。工程建好后先做三件事把项目名、包名、公司名这些基础信息填对包名后面改起来麻烦把色彩空间、图形 API 这些基础设置定下来然后立刻切平台。切平台这一步切完之后重新打开构建设置面板确认平台确实切过去了。我吃过一次教训点了切换编辑器在后台编译我以为切完了直接点构建结果出来的是另一个平台的包白等二十分钟。切过去之后面板里会出现跟小游戏相关的配置项最关键是 AppID 和资源压缩方式。AppID 填错的表现是构建能过、导入开发者工具报错压缩方式选错的表现是包更大或者加载更慢。压缩这块我一般选平台支持得最好的那种具体哪一项要看当前版本的支持矩阵选之前确认一下目标机型的兼容性。2.3 第一次构建先让空包在真机亮起来我在带人的时候有个硬性要求第一个里程碑不是功能跑通而是空包在真机上亮起来。这个顺序不能反因为只有把链路打通了后面所有问题才能区分是业务代码的问题还是环境的问题。具体做法是新建一个空场景场景里只放一个相机和一块纯色背景加一个显示帧率的文本然后直接构建。构建产物的目录结构大概是这个样子Build/wxminigame/ ├── index.html ├── game.js ├── game.json ├── unity.framework.js ├── unity.wasm.br └── data/不同版本的产物命名会有些差别但核心就这几样一个入口脚本、一个引擎运行时、一个编译出来的二进制、一个资源数据包。用开发者工具选择导入项目项目类型选小游戏目录指到构建产物的根目录导入后点编译如果模拟器里能看到那块纯色背景说明链路通了。真机验证这一步千万别省。模拟器和真机之间的差异大得离谱模拟器跑 60 帧的东西真机上可能只有 20 帧模拟器能正常播放的音频真机上没声音模拟器里内存充裕真机上一加载就崩。第一次就扫码上真机把能亮起来这件事确认死后面才有底气。注意真机预览的二维码有时效过期了重新生成就行不要以为是构建失败。3. Starter Kit 的骨架拆解3.1 目录结构与分层底座工程的目录结构我倾向于按职责分而不是按类型分。按类型分Scripts、Prefabs、Materials 这样在项目小的时候很清爽一旦超过两万行就开始混乱。按职责分的结构大概是这样Assets/ ├── _Project/ │ ├── Boot/ 启动场景与初始化脚本 │ ├── Core/ 状态机、事件总线、对象池 │ ├── Platform/ 平台能力抽象与实现 │ ├── Res/ 资源加载与分包调度 │ ├── UI/ 通用 UI 框架 │ └── Game/ 业务玩法 ├── _Art/ 美术资源按模块再分 └── _ThirdParty/ 第三方库隔离起来下划线前缀的作用是把这些目录顶到最前面视觉上和引擎自带目录分开。Platform这一层是重点它里面放的是接口定义和平台实现业务层只引用接口。这样一来如果哪天要出别的平台版本只需要再写一份实现业务代码一行不动。3.2 启动流程与状态机启动流程千万不要用一堆协程互相调用那样出了问题根本查不出来。用一个显式的状态机每个状态负责一件事状态之间通过明确的推进条件串联。public enum BootState { None, InitPlatform, // 平台 SDK 初始化 CheckVersion, // 资源版本检查 LoadMain, // 加载主场景 Ready } public class BootFlow : MonoBehaviour { private BootState _state BootState.None; private void Start() Enter(BootState.InitPlatform); private void Enter(BootState next) { _state next; Debug.Log($[Boot] - {next}); switch (next) { case BootState.InitPlatform: PlatformBridge.Instance.Init(ok { if (!ok) { ShowRetry(初始化失败); return; } Enter(BootState.CheckVersion); }); break; case BootState.CheckVersion: ResManager.Instance.CheckUpdate(p { SetProgress(p); }, ok Enter(ok ? BootState.LoadMain : BootState.None)); break; case BootState.LoadMain: ResManager.Instance.LoadScene(Main, () Enter(BootState.Ready)); break; } } }这段代码的价值不在于它多精妙而在于它把启动这个黑盒变成了四个可以独立打日志、独立重试的环节。用户卡在哪个环节日志里一眼就能看出来。我在实际项目里靠这个结构定位过至少五六次线上问题比如某次是平台初始化回调在某些机型上延迟特别久从日志的时间戳上一秒就能确认。3.3 平台能力抽象层平台 API 直接散落在业务代码里是后期维护的灾难。抽象层的写法不复杂核心是定义一个接口然后写一个实现类把平台 SDK 包起来。public interface IPlatformBridge { void Init(Actionbool onDone); void Login(Actionstring onCode, Actionstring onFail); void VibrateShort(); void Share(string title, string imageUrl); void ShowRewardAd(string adUnitId, Actionbool onResult); } public class WXBridge : IPlatformBridge { public void Init(Actionbool onDone) { WX.InitSDK(code { Debug.Log($[WX] init code{code}); onDone(code 0); }); } public void Login(Actionstring onCode, Actionstring onFail) { WX.Login(new LoginOption { success res onCode?.Invoke(res.code), fail err onFail?.Invoke(err.errMsg) }); } public void VibrateShort() WX.VibrateShort(new VibrateShortOption { type light }); public void Share(string title, string imageUrl) { WX.ShareAppMessage(new ShareAppMessageOption { title title, imageUrl imageUrl }); } public void ShowRewardAd(string adUnitId, Actionbool onResult) { var ad WX.CreateRewardedVideoAd(new WXCreateRewardedVideoAdParam { adUnitId adUnitId }); ad.OnClose(res onResult?.Invoke(res.isEnded)); ad.Show(); } }命名空间和类名在不同版本的 SDK 里会有出入上面这段按你本地实际类型名调整即可思路是一样的。要点有三个第一所有平台回调都要在回调里做异常保护平台回调抛异常有时候会直接把整个运行时打崩第二广告这类有实例生命周期的能力实例要缓存复用别每次展示都新建一个第三接口要设计成失败也有回调否则业务层会写出永远等不到结果的代码。3.4 资源与分包策略资源这块的核心矛盾是美术想要高精度包体不允许。解决方向只有两个一是把资源压缩到极致二是把资源挪出主包。主包里只放启动必需的资源Loading 图、字体、一个极简的主菜单。剩下的全部进分包。分包的划分粒度建议按玩法模块切不要按资源类型切因为按类型切所有图一个包、所有音效一个包会导致加载一个关卡要拉好几个包首次进入的等待时间长到用户直接退出。public void LoadSub(string pkgName, Action onDone, Actionstring onFail) { WX.LoadSubpackage(new LoadSubpackageOption { name pkgName, success _ { Debug.Log($[Res] subpackage {pkgName} ready); onDone?.Invoke(); }, fail e { Debug.LogError($[Res] {pkgName} fail: {e.errMsg}); onFail?.Invoke(e.errMsg); } }); }分包加载是异步的而且同一时间加载多个包可能互相拖慢所以调度层要做一个队列按优先级串行推进。我在一个项目里试过同时加载三个包结果是总耗时比串行还长因为网络请求互相抢占带宽。4. 核心环节实操把包体、内存、帧率摁住4.1 首包瘦身的六个动作首包体积是第一个绕不过去的硬指标。主包有明确的体积上限超了直接构建失败或者真机加载失败。我一般按下面这个顺序做瘦身从收益最大的开始。动作一引擎模块裁剪。在项目设置里把用不到的模块关掉物理、地形、视频播放、粒子系统的某些高级特性这些每个都占几百 KB。关之前确认一下依赖有些模块关掉会导致第三方插件编译不过。我见过一个项目因为用了某个 UI 插件被迫保留了一整套物理模块白占了一兆多。动作二代码裁剪等级拉到最高。托管代码裁剪等级提上去能砍掉大量没被引用的库代码。风险是反射调用的代码会被误删所以要配一份保留清单把通过字符串反射访问的类型写进去。动作三资源压缩格式统一。贴图按平台支持的最优格式压缩关掉用不到的 mipmap关掉读写权限。音频统一成小体积格式长音乐设成流式加载短音效设成压缩进内存。动作四剔除重复资源。这个最容易被忽略。同一个图集被打进两个不同的资源包体积就翻倍。定期跑一遍资源依赖分析把重复的合并掉。动作五字体裁剪。中文字体动辄几兆一定要做子集化只保留实际用到的字符。这一项经常能省下两三兆。动作六关闭无用的日志和调试符号。出正式包的时候把调试符号剥离日志级别调高这一项对体积影响不大但对加载速度有影响。做完这六项一个中等规模的 2D 项目主包控制在体积上限的一半以内是现实的。留一半余量是有必要的因为后面一定会不断往里塞东西。4.2 内存与帧率低端机才是真考场内存这块我建议直接拿一台三五年前的低端安卓机当基准设备所有性能验收都在这台机器上做。高端机上跑得飞起的项目在它上面可能连主菜单都进不去。首先要搞清楚内存花在哪。贴图通常是大头尤其是那些尺寸没控制好的 UI 图。一张 2048×2048 的不带压缩的图显存占用就是十几兆几十张这样的图叠起来低端机直接崩。解决办法就是严格控制尺寸和压缩格式UI 图能用 512 就别用 1024能用图集合并就别散着放。其次是托管堆。C# 的垃圾回收在小游戏的运行环境里开销比原生大频繁分配会产生明显的卡顿。做法很朴素热路径上不要 new字符串拼接改成缓存的构建器列表和字典提前预分配容量对象池该用就用。这些是老生常谈但真正做的时候代码里随手 new 的地方永远比你以为的多。// 反例每帧都在产生垃圾 void Update() { scoreText.text 得分 score / total; } // 改法只在数据变化时更新且用缓存 private int _lastScore -1; void Update() { if (score _lastScore) return; _lastScore score; _sb.Clear(); _sb.Append(得分).Append(score).Append( / ).Append(total); scoreText.text _sb.ToString(); }帧率方面先想清楚目标。动作类、需要跟手的玩法冲 60 帧休闲益智类锁 30 帧完全够用而且省电省发热用户体验反而更好。锁帧的做法是设置目标帧率并关掉垂直同步让引擎按你的节奏走。Draw Call 是另一个常见瓶颈。UI 层面靠图集合并解决确保同一个界面里的元素尽量来自同一张图集并且层级顺序上不要交叉。场景层面靠静态合批和材质共享同一种材质的物件尽量复用。4.3 真机调试与日志真机调试体验做得好不好直接决定排查效率。我的做法是在底座里内置一个简单的日志面板把关键日志同时输出到控制台和这个面板上真机上可以点开看。日志分级别正式的包里只保留警告和错误开发包全开。日志里一定要带时间戳和状态标记比如[Boot]、[Res]、[Net]这样的前缀出问题的时候按前缀过滤一眼就能看出是哪个环节挂了。还有一个实用技巧在启动流程的每个状态切换点记录一次时间戳最后打出一条汇总。这样一眼就能看出这个用户卡在资源检查花了 8 秒比翻几百行日志快得多。5. 常见问题排查实录5.1 构建与导入阶段的问题构建阶段最常见的问题是构建失败但报错信息极其含糊。这时候先看两件事平台是不是真的切过去了AppID 是不是填了。这两个是最基础也最容易被忽略的。导入开发者工具报错先看项目类型选对没有。选成小程序而不是小游戏表现是一堆文件识别不了。再看目录指对没有必须指到构建产物的根目录指到上一级或者下一级都会出问题。编译报包体积超限那就回到上一节的瘦身流程。这里有个坑有时候你删了资源但构建缓存里还留着旧的包体积下不来。清一次构建缓存重新出包往往能省下一大截。真机扫码后白屏这个最折磨人。排查顺序建议这样先在开发者工具里打开调试控制台看有没有报错如果没有报错但就是白屏检查首场景是不是在构建列表里且索引为 0如果场景没问题检查首场景里是不是有个能正常工作的相机和背景色。我遇到过一次是背景色设成了完全透明看起来就是白屏查了两个小时。5.2 运行期的问题运行期问题的表现形式五花八门但根源往往集中在几个地方。音频没声音九成是解锁问题。平台的音频策略要求首次播放由用户交互触发所以在启动流程里加一个点击开始的按钮在按钮回调里播一段静音或者极短的音频把通道打开后面的 BGM 就正常了。真机掉帧严重但模拟器流畅先看分辨率。有些项目在真机上跑的是设备全分辨率像素量是模拟器的好几倍。把渲染分辨率按设备能力做分级低端机降一档帧率立刻就上来了。接口请求失败但本机开发正常去查域名白名单。这个配置在平台侧不在代码里所以本机跑通了不代表真机能跑通。本地存储读不到检查是不是跨版本了。存储有容量上限写满了会静默失败读的时候拿到空值。做法是每次写入前先估算剩余空间超了就先清理旧数据。5.3 排查速查表现象最可能原因优先验证方式构建失败平台未切换 / AppID 未填看构建设置面板状态导入报错项目类型选错重新导入并选小游戏包体超限缓存未清 / 资源重复清缓存后重新构建对比真机白屏首场景配置 / 相机设置检查构建列表与场景内容无音频未做交互解锁加点击回调后重测掉帧渲染分辨率过高降档分辨率对比帧率接口失败域名白名单未配平台侧配置核对存储失效容量写满检查写入返回值内存崩溃贴图尺寸超标逐张排查大图提示这张表建议打印出来贴在工位上出问题的时候先照表过一遍能省下大量瞎猜的时间。6. 底座之上还能长出什么底座搭好之后接下来的扩展方向其实挺多的。我个人最推荐先做的是数据埋点因为小游戏的调优极度依赖真实数据哪个环节流失、哪一步加载慢光靠猜是不行的。埋点不用做得很重启动耗时、场景切换耗时、关键按钮点击、异常上报这四类数据足够支撑早期的决策了。第二个方向是自动化构建。把构建脚本挂到持续集成的流水线上每次提交自动出一个包传到内部分发渠道。这件事前期投入一两天后期每次发版省下的时间和避免的人为失误回报非常高。第三个方向是多平台兼容。抽象层如果一开始就设计对了后面接别的平台就是再写一份实现的事。我建议在底座里保留一个编辑器模拟实现让业务开发在编辑器里就能跑通完整流程不用每次都上真机这个开发效率的提升是很明显的。最后分享一个我个人踩过好几次的坑底座代码本身也要有版本管理而且要和业务工程分离。我见过太多团队把底座代码直接复制到每个项目里改了一份忘了另一份最后三四个项目的行为各不相同出了问题都不知道以哪份为准。把底座做成一个可以按版本引入的包这个习惯越早养成越好。帧率调优那部分我还想补一句别迷信 60 帧。有些休闲玩法锁 30 帧之后手机发热明显降低长时间玩下来体验反而更稳。这一点在小游戏这种随时打开随时关的场景里比多那 30 帧重要得多。
