微信小游戏 Unity 转换插件最佳实践检测工具：性能监控指标与优化指南

• 游戏开发
• 移动开发
• WebAssembly

关联文档：Design/PerformanceMonitor.md

导读

在微信小游戏平台上，Unity 游戏从启动到可交互的每个环节都可能成为性能瓶颈，而人工排查往往费时费力。本指南以本仓库（minigame-unity-webgl-transform）中 最佳实践检测工具文档 为核心，系统讲解微信小游戏 Unity 转换插件内置的最佳实践检测工具：如何开启与配置检测、如何解读启动 / 预下载 / wasm 分包 / 网络 / 帧率五大类监控指标，以及每个告警对应的优化手段与配套文档。读完本文，你将能够在开发阶段借助该工具快速定位启动慢、卡顿、网络利用率低等问题的根因，并据此实施精准优化。

作用

平台针对小游戏启动与运行阶段输出了大量优化手段，但优化前必须先"看见"问题。最佳实践检测工具的作用，就是让开发者在开发阶段即对游戏的实际表现进行体检：它会检测框架启动阶段的耗时与资源大小、预下载列表的使用情况、wasm 分包代码的加载时机、网络请求的并发与缓存利用，以及帧率与卡顿情况，并以弹框 + vconsole 日志的形式输出优化建议，帮助开发者针对具体问题逐一优化，避免上线后出现体验事故。

如何使用

版本要求与默认开启策略

• 版本要求：转换插件版本需大于202305230000，才能使用该检测能力。
• 默认开启：导出小游戏默认在开发版和体验版开启检测；线上（正式）版本不会执行检测，不会对线上用户产生任何开销。

检测的开关与行为通过minigame/unity-namespace.js中的monitorConfig配置对象控制，默认配置如下：

// 最佳实践检测配置 unityNamespace.monitorConfig = { enableMonitor: true, // 是否开启检测（只影响开发版/体验版，线上版本不会检测） fps: 10, // 帧率低于此值的帧会被记录，用于分析长耗时帧，做了限帧的游戏应该适当调低 showResultAfterLaunch: true, // 是否一直检测到游戏可交互完成 monitorDuration: 30000, // 仅当showResultAfterLaunch=false时有效, 在引擎初始化完成(即callmain)后多长时间停止检测 }

各配置项含义：

检测截止时机的选择

插件本身并不知道检测应该在何时截止，因此需要根据游戏的实际上报情况二选一：

1. 有上报游戏可交互的游戏：调用过WX.ReportGameStart()，应设置showResultAfterLaunch=true，检测将持续到游戏可交互完成；此时monitorDuration的值会被忽略。
2. 未上报游戏可交互的游戏：应设置showResultAfterLaunch=false，此时检测以monitorDuration指定的时长截止（从callmain完成算起）。

关于WX.ReportGameStart()的调用，可参考仓库中的 启动留存数据上报统计文档：当游戏完成所有加载、进入核心玩法（如休闲游戏进入核心玩法、MMO 游戏进入创角）时，调用 C# 接口上报：

// 所有加载完成，玩家可以交互时调用，用于标记检测截止点 WX.ReportGameStart();

检测示意

检测结果以三层形式呈现：弹框提醒、console 详细信息、完整检测报告。开发者可以按"先看弹框摘要 → 再看 console 明细 → 最后看完整报告"的顺序排查问题。

1. 弹框提醒优化建议

优化建议会通过弹框提示：

2. console 打印详细信息

详细内容通过 vconsole 打印：

3. console 打印检测报告

完整检测报告同样输出到 console，可着重关注网络和卡帧的数据：

检测指标解释

检测工具围绕五个维度输出指标与建议，下面逐一说明每个维度的监控字段、告警条件与配套优化手段。

启动检测

检查框架启动阶段的耗时和资源大小，用于判断首包下载、wasm 下载与引擎初始化是否拖慢启动。

监控指标

{ assetLoadCost: number; // 首资源包下载耗时，单位ms assetContentLength: number; // 首资源包大小(未压缩原始大小)，单位bytes useContentEncoding: boolean; // 首资源包是否开启服务器压缩 wasmLoadCost: number; // wasm包下载耗时，ms wasmContentLength: number; // 启动下载的wasm包大小，单位bytes useCodeSplit: boolean; // 是否使用了wasm代码分包 callmainCost: number; // 引擎初始化耗时，ms }

优化建议概览

当提示优化建议时，可采用对应的优化手段：

1. 未使用wasm代码分包

   • 条件：useCodeSplit为false，未使用 wasm 代码分包。
   • 优化手段：使用代码分包工具。

2. 首资源包较大

   • 条件：assetContentLength超过15 * 1024 * 1024，即未压缩的首资源包超过 15MB。
   • 优化手段：首资源包下载与体积。

3. 首资源包未开启服务器压缩

   • 条件：useContentEncoding值为false，服务器未开启 br 或 gzip。
   • 优化手段：首资源包下载与体积。

4. callmain耗时较长，请用安卓cpuprofile分析热点函数

   • 条件：iOS 平台callmainCost > 1500，或安卓平台callmainCost > 3000。
   • 优化手段：引擎初始化与开发者首帧逻辑。

预下载检测

检查预下载列表的使用情况，分为引擎初始化完成（callmain）时和检测完成时两个时间点的结果。vconsole 输出形如预下载基本信息: xxx , callmain完成时预下载信息: xxx，其中xxx为 js 对象。

监控指标

{ loadedCount: number; // 已预下载完成数量 loadingCount: number; // 正在预下载数量 loadedSizeStr: string; // 已预下载完成大小字符串表示, eg: 10.1MB loadedSize: number; // 已预下载完成大小，bytes hitCacheCount: number; // 命中CDN缓存的数量 useH2: boolean; // 是否启用HTTP2 useContentEncoding: boolean; // 是否开启了服务器压缩 preloadListLength: number; // 预下载资源个数 }

优化建议概览

1. 未使用预下载能力

   • 条件：preloadListLength = 0，即导出时未配置预下载列表。
   • 优化手段：使用预下载功能。

2. 已发起预下载，但未完成，请检查预下载资源是否过大，或是否下载过慢

   • 条件：引擎初始化完成时，loadingCount != 0且loadedCount = 0，表示预下载已发起但未完成。
   • 优化手段：使用预下载功能-注意事项第五点：预下载文件体积不应过大，应把优先需要使用的资源放到列表头部。

3. 预下载资源较小，请将大资源调整到预下载列表顶部

   • 条件：引擎初始化完成时loadedSize < 1 * 1024 * 1024（1MB），或停止检测时loadedSize < 5 * 1024 * 1024（5MB）。
   • 优化手段：适当增加预下载资源大小。

4. 预下载资源个数较多

   • 条件：preloadListLength > 15，即预下载列表数大于 15。
   • 优化手段：减小预下载个数。

5. 预下载资源量较大

   • 条件：loadedSize > 20 * 1024 * 1024（20MB），即总预下载大小超过 20MB。
   • 优化手段：减小预下载资源量。过大的资源下载会造成带宽抢占，推荐由游戏自行控制加载时机。

wasm分包检测

使用 wasm 代码分包后，检测工具会检查 wasm 分包代码的加载时机以及加载分包造成的卡顿时长，用来分析分包收集是否合理。若加载时机过早、阻塞时间过长，则需要优化。

tips：在新包做 wasm 分包期间可能会频繁提示优化建议，属于正常现象，迭代完成后再观察。

监控指标

{ loadSubWasmPackageStartTime: number; // 开始下载wasm子包的时间，ms loadSubWasmPackageCostTime: number; // （仅安卓）加载子包耗时，ms loadDurationCallmain: boolean; // 是否在引擎初始化期间加载子包 maxFetchPendingTime: number; // （仅iOS高性能）最大阻塞时间，ms。iOS高性能加载子包代码时会卡顿 costTimeAfterCallmain: number; // 引擎初始化完成后多长时间开始加载子包，ms }

优化建议概览

1. wasm子包在callmain期间加载，请使用分包工具继续收集

   • 条件：loadDurationCallmain = true。
   • 优化手段：分包收集不足，使用分包工具继续迭代。

2. wasm子包加载时机过早，请使用分包工具继续收集

   • 条件：costTimeAfterCallmain < 30000（30s）。
   • 优化手段：游戏前期不应加载子包；当前期出现子包加载，则需要继续迭代。

3. 缺失函数过多，请使用分包工具继续收集

   • 条件：maxFetchPendingTime > 2000。
   • 优化手段：iOS高性能模式收集、继续迭代。

网络信息检测

检查可缓存资源配置、CDN 配置、并发数、请求量、资源量，用于评估网络链路是否被充分利用、缓存策略是否合理。

监控指标

{ useH2: boolean, // 是否开启HTTP2.0 useContentEncoding: boolean, // 是否开启服务器压缩 cacheSettings: boolean, // settings.json是否自动缓存 cacheCatalog: boolean, // catalog.json是否自动缓存 appendHashToCatalog: boolean, // catalog.json是否带上了hash或其他用于区分版本的信息 requestCataHash: boolean, // 是否请求了catalog.hash文件用于资源热更新 requestBundleSettings: boolean, // 是否请求了settings.json requestBundleCatalog: boolean, // 是否请求了catalog.json loadCount: number, // 已发起请求数 loadedCount: number, // 已完成请求数 loadedSizeStr: string, // 请求回包总大小的字符串表示，eg: 10.1MB loadedSize: number, // 请求回包总大小，bytes hitCacheCount: number, // 命中CDN缓存个数 cacheableCount: number, // 可自动缓存个数 loadFromCacheCount: number, // 使用本地缓存的个数 startTime: number, // 首个请求开始时间 duration: number, // 监控时长 networkTime: number, // 有网络请求的总时长 maxLoadingCount: number, // 最大并发数，基于业务侧统计，会大于10个，表示有请求会排队 avgLoadingCount: number, // 平均并发数 loadedTasks: IBaseRequestInfo[], // 已下载完成请求详细信息 } // 请求详细信息如下 interface IBaseRequestInfo { url: string; // 请求URL startTime: number; // 请求开始时间 statusCode?: number; // 服务器状态码 enableContentEncoding?: boolean; // 是否开启了服务器压缩 endTime?: number; // 请求结束时间 duration?: number; // 请求耗时 protocol?: string; // 网络协议，h2或http1.1 receivedBytedCount?: number; // 回包大小，bytes hitCache?: boolean; // 是否命中CDN缓存 isReadFromCache?: boolean; // 是否使用本地缓存 cacheable?: boolean; // 是否自动缓存的资源 }

优化建议概览

1. 未开启http2

   • 条件：useH2 = false。
   • 优化手段：服务器开启 HTTP2.0。通过多路复用和头部压缩的特性，能提升细碎文件的下载效率。

2. 未命中CDN缓存

   • 条件：hitCacheCount = 0。
   • 优化手段：发布新版本时建议进行 CDN 预热，避免直接从源站拉取资源。

3. 请勿缓存settings.json

   • 条件：requestBundleSettings = true且cacheSettings = true。
   • 优化手段：Addressables 的settings.json文件用来记录打包配置，不应该缓存到本地。取消此文件的自动缓存，详见哪些资源会自动缓存。

4. 可将catalog.json配置为可缓存文件

   • 条件：requestBundleCatalog = true且cacheCatalog = false。
   • 优化手段：Addressables 的catalog.json记录了所有资源文件的描述信息和依赖关系，一般大小较大，推荐缓存到本地，详见哪些资源会自动缓存。

5. catalog.json被缓存且无hash/版本信息, 会导致无法更新

   • 条件：requestBundleCatalog = true且cacheCatalog = true且appendHashToCatalog = false。
   • 优化手段：catalog.json缓存到本地后若无版本标识，会导致无法更新到最新版本，详见缓存规则。

6. 请勿请求catalog.hash来做资源热更新，小游戏平台不支持

   • 条件：requestCataHash = true。
   • 优化手段：catalog.hash记录了catalog.json的 hash，用于热更新资源，但小游戏平台不支持。推荐使用catalog.json文件名带 hash 的方式来管理 catalog 版本，参见建议第五点。

7. 可缓存文件过少，检查缓存配置

   • 条件：cacheableCount < loadCount / 2，可缓存资源小于总请求数的一半。
   • 优化手段：检查缓存配置，确认资源文件大部分已缓存，提高可缓存数量。

8. 网络并发数过少

   • 条件：avgLoadingCount < 5，平均并发数小于 5。
   • 优化手段：并发数较少可能导致细碎文件较多时网络利用率不高，应在业务侧提高请求并发数。

9. 网络未充分利用

   • 条件：networkTime / duration < 0.7，网络时间占监控时长占比不足 70%。
   • 优化建议：可能由于游戏业务初始化逻辑较重、CPU 繁忙，在 CPU 繁忙时未充分利用网络空闲。建议在开始长耗时逻辑前，发起资源下载任务，充分利用网络。可配合微信开发者工具辅助分析。

帧率检测

检查是否有大长帧，标记大长帧出现的位置，辅助定位是CPU 耗时还是网络耗时导致启动慢。

监控指标

{ frames: string[]; // 长耗时的帧 frameCount: number; // 长耗时帧的个数 longestFrame: { // 最长帧信息 frame: string; // 帧数 frameCost: number; // 单帧耗时, ms runtime: number; // 游戏运行时长, ms }; frameInfo: IWrongFrame; // 长耗时帧信息 totalJankTime: number; // 总卡帧时长, ms currentRuntime: number; // 当前游戏运行时长, ms jankRate: number; // 卡顿率 }

优化建议概览

卡帧问题均需要使用 CPU Profiler 定位，可参考 使用Android CPU Profiler性能调优 与 使用Unity Profiler性能调优。

1. 存在长耗时帧cost=xxxms,runtime=xxxms

   • 条件：longestFrame.frameCost > 1000（1s）。

2. 总卡顿时长xxxms

   • 条件：totalJankTime > 5000（5s）。

3. 卡顿时长占比xx%

   • 条件：jankRate > 0.3。

优化分析工具

微信开发者工具

当检测报告提示"网络未充分利用"或需要进一步分析每帧耗时与网络并发的关系时，可以使用微信开发者工具自带的 performance 面板进行录制分析：

操作步骤：

• step1：点击调试器 - performance；
• step2：点击录制按钮开始录制；
• step3：分析网络并发和网络耗时；
• step4：查看每帧耗时，以及此帧的网络并发情况。

通过将"帧耗时"与"该帧网络并发"放在同一时间轴上对照，可以清晰判断某个长帧到底是由于 CPU 密集计算还是网络等待造成的，从而决定是优化业务逻辑（CPU）还是调整资源加载策略（网络）。

小结

最佳实践检测工具是微信小游戏 Unity 转换插件为开发者提供的一站式"开发期体检"能力，覆盖了启动、预下载、wasm 分包、网络、帧率五个维度的核心性能场景。建议的落地路径是：导出时保持enableMonitor: true→ 按游戏实际上报情况配置showResultAfterLaunch/monitorDuration→ 阅读弹框与 vconsole 的优化建议 → 结合 WasmSplit.md、StartupOptimization.md、UsingPreload.md、FileCache.md 等配套文档逐项优化 → 用微信开发者工具 performance 面板复核网络与帧率表现。通过这一闭环，可以显著缩短开发阶段的性能排查成本，让游戏在启动与运行两个阶段都达到更理想的性能状态。

• 游戏开发
• 移动开发
• WebAssembly