Merge pull request #802 from wechat-miniprogram/doc/launch-stage

zhangjunkunn · web-flow · commit 937fd282e4b5 · 2024-07-08T17:40:20.000+08:00
docs: 补充部分插件日志查看方式
diff --git a/Design/DataCDN.md b/Design/DataCDN.md
@@ -40,7 +40,7 @@
 
 ### 首资源包
 首资源包即`01367b188873c923.webgl.data.unityweb.bin.txt`，包含**Unity builtin + 勾选的导出场景 + Resources**资源。
-注意：加载方式取决于导出选项中的`首包资源加载方式`。同时由于小游戏总包体不能超过**20MB**，实际首包资源加载方式会根据包体决定，更多信息可查看[UnityLoader-首包资源加载方式](UsingLoader.md)
+注意：加载方式取决于导出选项中的`首包资源加载方式`。同时由于小游戏总包体不能超过**20MB**，实际首包资源加载方式会根据包体决定，更多信息可查看[UnityLoader-首包资源加载方式](UsingLoader.md#_3-3-首包资源加载方式)
 - 小游戏分包：因需要统计总包体大小，当导出时wasm代码brotli压缩正常的前提下，如果wasm代码+首包资源小于20MB，可使用"小游戏包内"加载，此时**不需要将首包资源部署到服务器**。
 - CDN：当不使用小游戏分包时，需要部署到服务器。
 
diff --git a/Design/FileCache.md b/Design/FileCache.md
@@ -1,4 +1,5 @@
 # 资源缓存
+- [资源缓存](#资源缓存)
 - [介绍](#介绍)
   - [一、什么情况触发资源缓存](#一什么情况触发资源缓存)
   - [二、哪些资源会自动缓存？](#二哪些资源会自动缓存)
@@ -12,9 +13,9 @@
         - [识别纹理资源版本](#识别纹理资源版本)
       - [缓存清理规则](#缓存清理规则)
     - [示例](#示例)
-  - [四、判断是否走缓存](#四判断是否走缓存)
-    - [查看详细日志](#查看详细日志)
-    - [查看缓存日志](#查看缓存日志)
+  - [四、查看缓存日志](#四查看缓存日志)
+    - [判断是否走缓存](#判断是否走缓存)
+    - [其他缓存日志](#其他缓存日志)
   - [五、注意项](#五注意项)
 
 # 介绍
@@ -56,7 +57,7 @@
 ```
 // 业务资源相关
 bundlePathIdentifier: 需要缓存的路径，用 `;`分隔 eg: StreamingAssets;bundles;
-excludeFileExtensions: 不需要缓存的文件类型，用 `;`分隔 eg: .json;.hash
+excludeFileExtensions: 当路径中包含字符时不需要缓存，用 `;`分隔 eg: .json;.hash
 bundleHashLength: bundle中hash占多少长度
 // 纹理相关
 needCacheTextures: 是否缓存纹理
@@ -68,16 +69,34 @@ maxStorage: 最大缓存容量，单位MB，默认值200MB
 ```
 
 其中部分配置可通过转换插件面板快速修改：
-`bundleExcludeExtensions`: 对应`不自动缓存文件类型`配置
-`bundleHashLength`: 对应`Bundle名中Hash长度`配置
+- `bundleExcludeExtensions` 对应 `不自动缓存文件类型` 配置
+- `bundleHashLength` 对应 `Bundle名中Hash长度` 配置
 
 #### 是否缓存规则
 存在业务的bundle资源和使用微信压缩纹理工具后的纹理资源，不同资源的缓存细节略有不同。
 ##### 是否缓存业务资源
 
 默认URL中包含`StreamingAssets`的请求会被识别为资源文件被自动缓存，可修改 `bundlePathIdentifier` 为你期望的值
 
-并非所有文件都适合持久化缓存，因此缓存规则也支持忽略某些文件，默认`.json`的文件不会被自动缓存，可修改 `bundleExcludeExtensions`。等同于修改**导出插件面板**的`不自动缓存文件类型`配置
+并非所有文件都适合持久化缓存，因此缓存规则也支持忽略某些文件，默认包含 `.json` 的文件不会被自动缓存，可修改 `bundleExcludeExtensions`。等同于修改**导出插件面板**的`不自动缓存文件类型`配置
+
+对应 js 代码，`minigame/unity-namespace.js`
+```ts
+// 判断是否需要自动缓存的文件，返回true自动缓存；false不自动缓存
+unityNamespace.isCacheableFile = function (path) {
+  // 判定为下载bundle的路径标识符，此路径下的下载，会自动缓存
+  const cacheableFileIdentifier = ["StreamingAssets"];
+  // 命中路径标识符的情况下，并不是所有文件都有必要缓存，过滤下不需要缓存的文件
+  const excludeFileIdentifier = [".json"];
+  if (
+    cacheableFileIdentifier.some(identifier => path.includes(identifier)
+        && excludeFileIdentifier.every(excludeIdentifier => !path.includes(excludeIdentifier)))
+  ) {
+    return true;
+  }
+  return false;
+};
+```
 
 ##### 是否缓存纹理
 默认会缓存纹理，修改`needCacheTextures`可控制是否缓存纹理资源。
@@ -145,7 +164,7 @@ unityNamespace.isErasableFile = function (info) {
 URL剔除掉DATA_CDN部分后作为缓存路径
 例如：
 - DATA_CDN=https://weixin.qq.com/webgl
-- 请求路径=https://weixin.qq.com/webgl/StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e
+- 资源下载URL=https://weixin.qq.com/webgl/StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e
 
 那么：
 - 则缓存路径=${wx.env.USER_DATA_PATH}StreamingAssets/textures_8d265a9dfd6cb7669cdb8b726f0afb1e
@@ -176,26 +195,27 @@ defaultReleaseSize: 清理时，默认额外清理的大小，单位Bytes，1MB
 maxStorage: 最大缓存容量，修改此值需要联系研发助手开通权限，否则无效
 ```
 
-## 四、判断是否走缓存
-### 查看详细日志
-1. `minigame/unity-namespace.js`打开详细日志开关`enableDebugLog: true`
-2. 打开调试
-- 开发者工具：调试器->Console
-- 真机：
-  步骤1(打开调试模式)：右上角菜单->打开调试->出现vconsole 或者 game.js增加代码"wx.setEnableDebug({enableDebug: true})"
-  步骤2(打开vconsole)：点击vconsole打开日志面板（启动阶段点三次封面视频下方Unity Logo出现 vconsole)
+## 四、查看缓存日志
+[查看插件调试日志](UsingLoader.md#_3-6-插件调试日志)
 
-### 查看缓存日志
+### 判断是否走缓存
 1. 自动缓存
 出现以下两种日志，都可认为需要自动缓存
 - `[PLUGIN LOG 10:32.52.915]  CacheXMLHttpRequest_onload: shadowreceiverdepth_9551162e.bundle, 耗时:222ms,无缓存，执行缓存逻辑`
 - `[PLUGIN LOG 10:32.53.073]  缓存 shadowreceiverdepth_9551162e.bundle成功;size: 1.78KB,耗时: 79ms`
 2. 命中本地缓存: `[PLUGIN LOG 20:18.38.275]  CacheXMLHttpRequest_onload: scene999_tw_5b9ef7d7.bundle使用缓存, 耗时:37ms`
 
+### 其他缓存日志
+1. `删除 xxx 旧缓存`：清理同名文件旧缓存
+2. `需要释放xxMB存储空间`：达到缓存上限，需要释放的空间大小
+3. `缓存文件数=xxx, 总文件大小=xxx`：当前缓存目录总文件数和总文件大小（单位 bytes）
+4. `删除文件: xx, md5:xx, size:xx, 耗时: xx`：清理旧缓存或达到缓存上限时删除文件
+
 ## 五、注意项
 1. 文件名需要带上hash [BuildAssetBundleOptions.AppendHashToAssetBundleName](https://docs.unity3d.com/ScriptReference/BuildAssetBundleOptions.AppendHashToAssetBundleName.html)，以便清理掉该文件的旧缓存。默认32位长度，可通过导出选项中`Bundle名中Hash长度`来自定义。比如游戏自己计算了crc，可将`Bundle名中Hash长度`设置为crc长度。
 2. 配置到不自动缓存文件类型中的文件，不会自动缓存，默认值是json，比如addressable打包后生成StreamingAssets/aa/WebGL/catalog.json，这个文件不会自动缓存。
 3. 开发者工具上可以打开文件系统查看缓存文件
+4. 当文件没有正常缓存时，着重检查 缓存规则 中 `资源下载URL` 、`DATA_CDN`、和 `bundlePathIdentifier`，当`资源下载URL`中不包含`DATA_CDN`时，不会走缓存逻辑。
 
 缓存文件在usr目录下
 
diff --git a/Design/PerformanceMonitor.md b/Design/PerformanceMonitor.md
@@ -42,7 +42,7 @@ unityNamespace.monitorConfig = {
 
 默认检测条件如上。插件并不知道什么时候检测截止，可选择可交互上报后或在引擎初始化完成(`callmain`)后多少ms截止，根据游戏实际情况修改。
 
-1. 有上报游戏可交互[`WX.ReportGameStart()`](ReportStartupStat.md#三上报自定义阶段)的游戏
+1. 有上报游戏可交互[`WX.ReportGameStart()`](ReportStartupStat.md#三、上报自定义阶段)的游戏
 应该设置`showResultAfterLaunch=true`，同时会忽略`monitorDuration`的值
 
 1. 未上报游戏可交互上报的游戏
@@ -89,15 +89,15 @@ unityNamespace.monitorConfig = {
 
 2. `首资源包较大`
 - 条件: `assetContentLength`超过15 * 1024 * 1024，即未压缩的首资源包超过15MB
-- 优化手段: [首资源包下载与体积](StartupOptimization.md#221-首资源包下载与体积)
+- 优化手段: [首资源包下载与体积](StartupOptimization.md#_2-2-1-首资源包下载与体积)
 
 3. `首资源包未开启服务器压缩`
 - 条件: `useContentEncoding`值为`false`，服务器未开启br或gzip
-- 优化手段: [首资源包下载与体积](StartupOptimization.md#221-首资源包下载与体积)
+- 优化手段: [首资源包下载与体积](StartupOptimization.md#_2-2-1-首资源包下载与体积)
 
 4. `callmain耗时较长，请用安卓cpuprofile分析热点函数`
 - 条件: iOS平台`callmainCost>1500`或安卓平台`callmainCost>3000`
-- 优化手段: [引擎初始化与开发者首帧逻辑](StartupOptimization.md#223-引擎初始化与开发者首帧逻辑)
+- 优化手段: [引擎初始化与开发者首帧逻辑](StartupOptimization.md#_2-2-3-引擎初始化与开发者首帧逻辑)
 
 ### 预下载检测
 检查预下载列表使用情况，分为引擎初始化完成(`callmain`)和检测完成时两个结果
@@ -226,23 +226,23 @@ interface IBaseRequestInfo {
 
 3. `请勿缓存settings.json`
 - 条件: `requestBundleSettings=true` 且 `cacheSettings=true`
-- 优化手段: Addressables的`settings.json`文件用来记录打包配置，不应该缓存到本地。取消此文件的自动缓存，[哪些资源会自动缓存](FileCache.md#二哪些资源会自动缓存)
+- 优化手段: Addressables的`settings.json`文件用来记录打包配置，不应该缓存到本地。取消此文件的自动缓存，[哪些资源会自动缓存](FileCache.md#二、哪些资源会自动缓存)
 
 4. `可将catalog.json配置为可缓存文件`
 - 条件: `requestBundleCatalog=true` 且 `cacheCatalog=false`
-- 优化手段: Addressables的`catalog.json`记录了所有资源文件的描述信息和依赖关系，一般大小较大，推荐缓存到本地，[哪些资源会自动缓存](FileCache.md#二哪些资源会自动缓存)
+- 优化手段: Addressables的`catalog.json`记录了所有资源文件的描述信息和依赖关系，一般大小较大，推荐缓存到本地，[哪些资源会自动缓存](FileCache.md#二、哪些资源会自动缓存)
 
 5. `catalog.json被缓存且无hash/版本信息, 会导致无法更新`
 - 条件: `requestBundleCatalog=true` 且 `cacheCatalog=true` 且 `appendHashToCatalog=false`
-- 优化手段: `catalog.json`缓存到本地若无版本标识，会导致无法更新到最新版本, [缓存规则](FileCache.md#三缓存规则)
+- 优化手段: `catalog.json`缓存到本地若无版本标识，会导致无法更新到最新版本, [缓存规则](FileCache.md#三、缓存规则)
 
 6. `请勿请求catalog.hash来做资源热更新，小游戏平台不支持`
 - 条件: `requestCataHash=true`
 - 优化手段: `catalog.hash`记录了`catalog.json`的hash，用来热更新资源，但小游戏平台不支持，推荐使用`catalog.json`文件名带hash的方式来管理catalog版本，参见建议第五点
 
 7. `可缓存文件过少，检查缓存配置`
 - 条件: `cacheableCount < loadCount / 2`，可缓存资源小于总请求数的一半
-- 优化手段: 检查[缓存配置](FileCache.md#二哪些资源会自动缓存)，是否资源文件大部分未缓存。提高可缓存数量
+- 优化手段: 检查[缓存配置](FileCache.md#二、哪些资源会自动缓存)，是否资源文件大部分未缓存。提高可缓存数量
 
 8. `网络并发数过少`
 - 条件: `avgLoadingCount < 5`，平均并发数小于5
diff --git a/Design/ReportStartupStat.md b/Design/ReportStartupStat.md
@@ -118,6 +118,19 @@ gameManager.onLaunchProgress = (e) => {
 }
 ```
 
+类型枚举
+```js
+export const launchEventType = {
+  launchPlugin: 0, // 插件启动
+  loadWasm: 1, // 下载wasm代码
+  compileWasm: 2, // wasm代码编译
+  loadAssets: 3, // 下载首资源包
+  unzipAssets: 4, // 解压首资源包
+  readAssets: 5, // 读取首资源包
+  prepareGame: 6, // 引擎初始化
+};
+```
+
 ## 五、获取数据统计
 
 > 请注意！需前往【公众平台 - 能力地图 - 生产提效包 - 快适配 】开通后，方可查看数据
diff --git a/Design/UsingAddressable.md b/Design/UsingAddressable.md
@@ -36,7 +36,7 @@ Unity中资源按需加载也可以使用老的AssetBundle，然而使用AB需
 
 ### 2.4 使用WXAssetBundleProvider节省内存
 
-[WXAssetBundle](UsingAssetBundle.md#三更节省内存的wxassetbundle)可以减轻iOS的内存压力，对于使用Addressable的项目，需要替换Provider来使用WXAssetBundle。
+[WXAssetBundle](UsingAssetBundle.md#三、更节省内存的wxassetbundle)可以减轻iOS的内存压力，对于使用Addressable的项目，需要替换Provider来使用WXAssetBundle。
 
 1. 下载[WXAssetBundleProvider.cs](https://github.com/wechat-miniprogram/minigame-unity-webgl-transform/blob/main/tools/WXAssetBundleProvider.cs)，放到WX-WASM-SDK-V2/Runtime/目录下
 2. 导入插件后会有WXAssetBundleProvider.cs缺依赖的报错，需要给WX-WASM-SDK-V2/Runtime 增加 Unity.ResourceManager 的引用
diff --git a/Design/UsingAssetBundle.md b/Design/UsingAssetBundle.md
@@ -97,7 +97,7 @@ public static void Build()
 
 - 使用说明
 
-  Addressable也可使用，可参考[使用WXAssetBundleProvider节省内存](UsingAddressable.md#24-使用wxassetbundleprovider节省内存) 修改Provider。
+  Addressable也可使用，可参考[使用WXAssetBundleProvider节省内存](UsingAddressable.md#_2-4-使用wxassetbundleprovider节省内存) 修改Provider。
 
   AssetBundle目前只支持异步加载。参考示例如下：
 
diff --git a/Design/UsingLoader.md b/Design/UsingLoader.md
@@ -103,7 +103,14 @@ let managerConfig = {
 loader会自动按一定规则做文件缓存，加快二次启动速度
 详情参考[资源缓存](FileCache.md)
 
-### 3.6 插件调试信息
-通过修改`minigame/unity-namespace.js` 中 `enableDebugLog=true`，可查看插件详细日志，例如预下载发起和命中、文件缓存等。
+### 3.6 插件调试日志
+1. 通过修改`minigame/unity-namespace.js` 中 `enableDebugLog=true`，可查看插件详细日志，例如预下载发起和命中、文件缓存等。
+2. 打开调试
+- 开发者工具：调试器->Console
+- 真机：
+  - 步骤1(打开调试模式)：右上角菜单->打开调试->出现vconsole 或者 game.js增加代码
+  ```js
+  wx.setEnableDebug({enableDebug: true})
+  ```
+  - 步骤2(打开vconsole)：点击vconsole打开日志面板（启动阶段点三次封面视频下方Unity Logo出现 vconsole)
 
-> 真机需通过右上角菜单-调试-打开调试，查看小游戏日志
diff --git a/Design/UsingPreload.md b/Design/UsingPreload.md
@@ -2,7 +2,9 @@
 ## 概述
 通过 [启动流程与时序](Startup.md)我们知道，在UnityLoader加载过程中存在**网络空闲**的情况。特别是“引擎初始化和首场景准备”，影响该步骤包括：引擎自身模块与数据初始化，游戏首个场景加载以及Awake流程。这个过程是CPU处理密集，但网络空闲的期间，根据机型性能不同，通常**平均耗时会在3~6s**左右，我们可以在此阶段提前下载资源。
 
-在引擎初始化期间，最多**并发10个**预下载。已发起但未完成的下载任务，以及列表中尚未发起的任务，会在引擎初始完成后继续进行，但**并发数为1个**。可通过Csharp接口 `WX.PreloadConcurrent` 修改引擎初始化后的预下载并发数，若想修改引擎初始化期间的并发数，需要使用js接口 `GameGlobal.manager.setConcurrent`
+预下载的列表的原理是提前通过网络下载资源并缓存到本地，下次使用时从本地缓存中读取文件，以此提高资源加载速度。
+
+同时，我们认为添加到预下载列表的资源都是需要尽快使用到的资源，因此，资源在预下载完成后，会在内存中持有 60s 后释放，从而降低命中预下载列表时的文件读取耗时。
 
 ## 配置方式
 ### 导出预下载列表
@@ -119,12 +121,25 @@ public class PreloadListData
 }
 ```
 
+## 并发数
+在引擎初始化完成前，默认**并发10个**预下载。已发起但未完成的下载任务，以及列表中尚未发起的任务，会在引擎初始完成后继续进行，但**并发数改为1个**。可通过Csharp接口 `WX.PreloadConcurrent` 修改引擎初始化后的预下载并发数，若想修改引擎初始化期间的并发数，需要使用js接口 `GameGlobal.manager.setConcurrent`
+- 默认值：引擎初始化完成前 10 个；引擎初始化完成后 1 个
+- 最大值：10 个
+
+> 即使通过 `GameGlobal.manager.setConcurrent` 修改并发数，在引擎初始化完成后仍会重置为 1 个，需再次修改为你需要的值
+
 ## 路径规范
 - 若填写完成路径，如`$STREAM_CDN/StreamingAssets/WebGL/textures_8d265a9dfd6cb7669cdb8b726f0afb1e`；实际发起预载请求的URL采用填写的地址
 - 若填写相对路径，如`/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2`；实际发起请求的URL为`DATA_CDN/StreamingAssets/WebGL/sounds_97cd953f8494c3375312e75a29c34fc2`
 
 ## 如何验证
-[查看插件调试信息](UsingLoader.md#36-插件调试信息), 当存在 `PreloadManager:` 字样日志，即为预下载。
+[查看插件调试日志](UsingLoader.md#_3-6-插件调试日志)
+1. 当存在 `PreloadManager:` 字样日志，即为预下载请求日志。
+2. 当存在 `xhr: xx使用预载内容` 即为复用内存中已预下载完成的资源，不发起网络请求。
+3. 当存在 `xhr: xx 等待预载完成` 即为复用未完成的预下载网络链接，等待网络完成。
+
+> tips：当预下载完成时间超过 60s 后，内存中的资源会释放。后续请求已预下载的资源没有日志可以区分，可通过 `PreloadManager:` 验证此资源预下载成功
+
 
 ## 注意事项
 1. 预下载所有文件总体积应控制在合理范围内，通常可以3~5MB左右的内容。
diff --git a/Design/WXFont.md b/Design/WXFont.md
@@ -10,7 +10,7 @@
 - 安卓微信客户端版本 >= 8.0.34
 - iOS微信客户端版本 >= 8.0.39
 
-若不满足客户端版本要求，首次从网络下载，当符合缓存规则时，后续从[本地文件缓存加载](FileCache.md)
+若不满足客户端版本要求，首次从网络下载；当符合缓存规则时，后续从[本地文件缓存加载](FileCache.md)，因此必须提供 CDN 后备字体。
 
 ## 代码示例
 详细示例可参考[系统字体demo](https://github.com/wechat-miniprogram/minigame-unity-webgl-transform/tree/main/Demo/WX_Font)
@@ -24,6 +24,20 @@ WeChatWASM.WX.GetWXFont(fallbackFont, (font) =>
 });
 ```
 
+## 相关日志
+- 打开[插件调试日志](UsingLoader.md#_3-6-插件调试日志)
+- 日志中查看以下字样 `[PLUGIN LOG xxx][font]`，例如
+  - 使用微信字体：
+    - `[PLUGIN LOG xxx][font] load font from local`
+    - `[PLUGIN LOG xxx][font]读取字体文件耗时=xxms, 字体大小=xxMB`
+  - 使用网络字体：
+    - `[PLUGIN LOG xxx][font] load font from network, url=https://www......com/字体文件.ttf`
+    - `[PLUGIN LOG xxx]xhr_onload: 字体文件.ttf,耗时=xxms,size=xx,无缓存`
+
+异常日志：
+- `[PLUGIN LOG xxx][font]无中文字体`：本地无可用系统字体，常见为安卓系统版本低于7.1
+- `[PLUGIN LOG xxx][font]无字体文件内容`：读取字体文件失败，未知原因，可提供微信日志给平台侧排查
+
 ## 系统字体字符集
 
 使用GetWXFont加载的字体集合可以在转换面板进行自定义，以减少加载的字体文件大小：
diff --git a/package-lock.json b/package-lock.json
