mini-three-adapter 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/AGENTS.md +85 -85
  2. package/README.md +159 -159
  3. package/dist/build/rollup.js +60 -9
  4. package/dist/build/rollup.js.map +1 -1
  5. package/dist/build/vite.js +60 -9
  6. package/dist/build/vite.js.map +1 -1
  7. package/dist/{chunk-MTBMOFAL.js → chunk-CQPWOYLA.js} +27 -14
  8. package/dist/chunk-CQPWOYLA.js.map +1 -0
  9. package/dist/{chunk-LB3WL24R.js → chunk-LRR4AEZM.js} +8 -4
  10. package/dist/chunk-LRR4AEZM.js.map +1 -0
  11. package/dist/{chunk-3UGQWFH3.js → chunk-MWGTYPGA.js} +87 -27
  12. package/dist/chunk-MWGTYPGA.js.map +1 -0
  13. package/dist/{chunk-4UEBRAK6.js → chunk-TMSB525P.js} +15 -6
  14. package/dist/chunk-TMSB525P.js.map +1 -0
  15. package/dist/{chunk-WLRQDTSZ.js → chunk-V2IGFCZV.js} +3 -3
  16. package/dist/{chunk-WLRQDTSZ.js.map → chunk-V2IGFCZV.js.map} +1 -1
  17. package/dist/{chunk-Z7AMDRN3.js → chunk-WB6MOHR3.js} +8 -5
  18. package/dist/chunk-WB6MOHR3.js.map +1 -0
  19. package/dist/core/index.d.ts +15 -5
  20. package/dist/core/index.js +2 -2
  21. package/dist/index.d.ts +2 -2
  22. package/dist/index.js +6 -6
  23. package/dist/platforms/browser.d.ts +2 -2
  24. package/dist/platforms/browser.js +3 -3
  25. package/dist/platforms/wechat-game.d.ts +2 -2
  26. package/dist/platforms/wechat-game.js +4 -4
  27. package/dist/platforms/wechat-miniprogram.d.ts +2 -2
  28. package/dist/platforms/wechat-miniprogram.js +4 -4
  29. package/dist/polyfills/index.d.ts +8 -1
  30. package/dist/polyfills/index.js +1 -1
  31. package/dist/{runtime-7uUOoFhC.d.ts → runtime-DnEkKZjo.d.ts} +1 -1
  32. package/dist/scope.d.ts +1 -1
  33. package/dist/{types-BzK0LQMa.d.ts → types-X_5SJh4y.d.ts} +7 -0
  34. package/docs/02-architecture.md +126 -126
  35. package/docs/03-module-map.md +99 -99
  36. package/docs/04-api-reference.md +294 -291
  37. package/docs/05-build-plugin.md +33 -5
  38. package/docs/06-platform-notes.md +113 -108
  39. package/docs/07-integration-guide.md +13 -0
  40. package/docs/09-testing-and-release.md +208 -206
  41. package/docs/10-ai-playbook.md +140 -140
  42. package/docs/11-compat-matrix.md +95 -94
  43. package/docs/adr/0007-capability-probe-fallback.md +55 -0
  44. package/docs/adr/README.md +1 -0
  45. package/llms.txt +68 -65
  46. package/package.json +10 -4
  47. package/dist/chunk-3UGQWFH3.js.map +0 -1
  48. package/dist/chunk-4UEBRAK6.js.map +0 -1
  49. package/dist/chunk-LB3WL24R.js.map +0 -1
  50. package/dist/chunk-MTBMOFAL.js.map +0 -1
  51. package/dist/chunk-Z7AMDRN3.js.map +0 -1
@@ -21,12 +21,21 @@ flowchart TD
21
21
  C --> D["traverse: ReferencedIdentifier"]
22
22
  D --> E{"name ∈ DEFAULT_GLOBAL_NAMES?"}
23
23
  E -->|否| D
24
- E -->|是| F{"非计算属性键 / 成员属性?"}
25
- F -->|是| D
26
- F -->|否| G{"path.scope.hasBinding(name, true)?"}
24
+ E -->|是| F{"简写属性 { X }?"}
25
+ F -->|是| H1["展开:X: (__m3().X)"]
26
+ F -->|否| F2{"非计算属性键 / 成员属性?"}
27
+ F2 -->|是| D
28
+ F2 -->|否| G{"path.scope.hasBinding(name, true)?"}
27
29
  G -->|是(局部/import/参数)| D
28
- G -->|否(真正的自由全局)| H["MagicString.overwrite<br/>name → __m3().name"]
29
- H --> I["prepend:<br/>import { getActiveScope as __m3 } from 'mini-three-adapter/scope'"]
30
+ G -->|否(真正的自由全局)| G2{"typeof 的操作数?"}
31
+ G2 -->|是| H2["(__m3Has() ? __m3().X : undefined)"]
32
+ G2 -->|否| G3{"new 的 callee 成员链根?"}
33
+ G3 -->|是| H3["(__m3().X),由外层 new 结合"]
34
+ G3 -->|否| H4["name → __m3().name"]
35
+ H1 --> I["prepend:<br/>import { getActiveScope as __m3 } from 'mini-three-adapter/scope'<br/>(用到 typeof 守卫时追加 hasActiveScope as __m3Has)"]
36
+ H2 --> I
37
+ H3 --> I
38
+ H4 --> I
30
39
  I --> J["返回 { code, map }"]
31
40
  ```
32
41
 
@@ -38,10 +47,18 @@ flowchart TD
38
47
  | `const o = { window: 1 }` | 非计算属性键 → 不改写 |
39
48
  | `foo.window` | 成员属性 → 不改写 |
40
49
  | `import { window as w } from 'x'` | import 绑定 → 不改写 |
50
+ | `new TextDecoder()` | 改写成 `new (__m3().TextDecoder)()`。**括号不能省**:`new __m3().TextDecoder()` 会被解析成 `(new __m3()).TextDecoder()`,于是 scope 对象被当成构造函数、类被普通调用,报 `Class constructor ... cannot be invoked without 'new'` |
51
+ | `new OffscreenCanvas(1, 1).getContext('2d')` | 只给链根加括号 → `new (__m3().OffscreenCanvas)(1, 1).getContext('2d')`,语义不变 |
52
+ | `const o = { TextDecoder }` | 展开成 `{ TextDecoder: (__m3().TextDecoder) }`。简写属性的 key 与 value 是两个**区间相同**的独立节点,原地替换会产出 `{ __m3().TextDecoder }` 这种**语法错误**,因此必须展开 |
41
53
  | `typeof window !== 'undefined'` | 改写成 `typeof __m3().window !== 'undefined'`,结果 `'object'`,three 走浏览器分支(正是我们想要的) |
54
+ | `typeof document !== 'undefined'` | 改写成 `typeof (__m3Has() ? __m3().document : undefined)`:runtime 未创建时得到 `'undefined'` 而不是抛错;runtime 存在时照常返回真实对象 |
42
55
  | `URL.createObjectURL(blob)` | `URL` 与 `Blob` 都改写 |
43
56
  | 解析失败 | 记录 `parseFailures` + `ctx.warn`,**原样返回**,绝不产出半改写代码 |
44
57
 
58
+ > 为什么只有 `new` 需要括号:`typeof`、`in`、`delete`、`?.`、`instanceof` 右侧等位置,`__m3().X` 的优先级都足够高;唯一优先级倒挂的是 `new`。
59
+
60
+ > 为什么 `typeof` 要单独守卫:`typeof` 是本应永不抛错的运算符,而 `emptyScope` 对未初始化的 `document` 等键会抛出可读错误。不加守卫时,库顶层的 `const isBrowser = typeof document !== 'undefined'` 会在 runtime 创建之前直接崩掉,而报错指向适配层,极易误判为「初始化顺序写错」。守卫只加在 `window/self/globalThis` 之外的名字上,因为这三个在 `emptyScope` 里恒指向自身。
61
+
45
62
  `globalThis` **故意不在**默认清单里:three 会用它挂调试钩子(`__THREE_DEVTOOLS__` 等),改写会破坏这些逻辑。
46
63
 
47
64
  `forceUndef: ['createImageBitmap']`:这些名字同样被改写,但作用域里恒为 `undefined`,于是 three 的 `typeof createImageBitmap !== 'undefined'` 判定为假,自动走非 Blob 分支。宿主环境提供了该 API 却没有原生 `Blob` 实现时,这个开关可以让 three 绕开不可用的代码路径。
@@ -144,3 +161,14 @@ console.log(plugin.api.report());
144
161
  | 解析报错 | `report.parseFailures`,考虑给 `rewrite` 加语法插件或 `exclude` 该模块 |
145
162
  | worker/wasm 没进包 | `report.assetReferences` / `missingAssets`;补 `roots` |
146
163
  | 包体过大 | 参照 `gameJsonSuggestion` 分包;`manualChunks` 见 [`examples/wechat-minigame/vite.config.ts`](../examples/wechat-minigame/vite.config.ts) |
164
+
165
+ ### 按报错文案反查
166
+
167
+ | 报错 | 含义 | 处理 |
168
+ | --- | --- | --- |
169
+ | `Class constructor xxx cannot be invoked without 'new'`(栈顶常是 `GLTFLoader.js:444`) | 改写产物把 `new TextDecoder()` 变成了 `(new __m3()).TextDecoder()` | 升级到含本修复的版本;宿主侧临时补丁见下 |
170
+ | `SyntaxError: Unexpected token '.'`,指向 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
171
+ | `Scoped global "document" was read before a runtime was created` | 真的在 runtime 之前读了 `document`(不是 `typeof`) | 按 [`docs/07`](./07-integration-guide.md#74-入口改造最关键的一步) 调整入口顺序 |
172
+ | `new __m3().X` 残留 | 适配层版本过旧 | 检查 `dist` 里的重写器版本,清理缓存后重建 |
173
+
174
+ 临时规避(仅用于旧版本):在适配层插件**之后**(`enforce: 'post'`)跑一段产物级正则,把 `new __m3().X()` 改成 `new (__m3().X)()`。它依赖访问器名与「空参数」两个特征,适配层改了默认 `accessor` 就会静默失效,因此修复到位后应当删除。
@@ -1,108 +1,113 @@
1
- # 06 · 微信小游戏平台差异、已知坑与诊断
2
-
3
- > 平台规范:[微信开放文档 · Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)、[渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)、[WXWebAssembly](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html)、[iOS 高性能模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html),以及小游戏配置(game.json)说明。
4
-
5
- ## 6.1 运行时基本事实
6
-
7
- | 事实 | 对本适配层的约束 |
8
- | --- | --- |
9
- | iOS = JavaScriptCore,Android = V8;**无 DOM/BOM**,无全局 `document`/`window` | 必须由 `MiniThreeScope` 提供 shim |
10
- | 基础库不附带 DOM 兼容层,需由应用自行引入 | 适配层不假设宿主已存在任何兼容对象 |
11
- | 首次 `wx.createCanvas()` 得到唯一**上屏画布**,后续均为离屏 | `getScreenCanvas()` 必须只调用一次并缓存;能力探测只能用 `createOffscreenCanvas` |
12
- | `Canvas.getContext('webgl2')` 返回标准 WebGL2 上下文 | three ≥ r163 需要 WebGL2;默认 `defaultContextType: 'webgl2'` |
13
- | `wx.setPreferredFramesPerSecond` 可锁帧 | `createWeChatGameRuntime({ preferredFps })` |
14
- | 基础库 2.13.0+ `WXWebAssembly`,2.15.0+ Worker 内可用;支持 `.wasm` / `.wasm.br` | 插件 `brotli` 选项、资产分包 |
15
- | Worker 并发上限 **1**,目录只能放 JS,分包需先 `preDownloadSubpackage` | 所有 worker/wasm 输出到一个 `outputDir` |
16
- | iOS 高性能+ 建议用于 WebGL2 / 内存压力大的游戏 | `game.json` 的 `iOSHighPerformance+`;见 §6.5 |
17
-
18
- ## 6.2 导入顺序(最容易踩的坑)
19
-
20
- ESM 静态导入会在模块体执行之前求值。若入口文件顶部写了 `import * as THREE from 'three'`,而 `createRuntime()` 在下面才执行,则 three 模块初始化期间读到的仍是占位作用域。
21
-
22
- **推荐**:入口只导入适配层,用动态 import 加载场景:
23
-
24
- ```ts
25
- import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
26
- const runtime = await createWeChatGameRuntime();
27
- const { startScene } = await import('./scene.js'); // scene.js 里才 import three
28
- ```
29
-
30
- **兜底**:`createWeChatGameRuntime({ installGlobals: true })`,把 shim 显式挂到 `globalThis`(可逆),适合无法改导入结构的老项目。
31
-
32
- 诊断:占位作用域在真正取属性时会抛
33
- `Scoped global "xxx" was read before a runtime was created`,直接提示上述两种解法。
34
-
35
- ## 6.3 已知坑位与处理
36
-
37
- | 症状 | 原因 | 本项目处理 |
38
- | --- | --- | --- |
39
- | `createImageBitmap` 相关报错 | PC 小程序提供了该函数却没有原生 `Blob` | `scope.createImageBitmap = undefined`,插件 `forceUndef` 保证 three 走降级分支 |
40
- | `PMREMGenerator.fromScene` 返回纯黑贴图 | 部分设备 WebGL 深度缓冲未清除 | 不在运行时改写 `WebGLRenderer.render`。应用层按需:每次 render 后 `renderer.clearDepth()`,或配置 `renderer.autoClearDepth`。见下方代码 |
41
- | 开发者工具报 `Unexpected token` | `node_modules` 里用了较新语法 | 构建 `target: 'es2019'`(消除 `?.` / `??`);必要时开发者工具开启「将 JS 编译成 ES5」或加 Babel |
42
- | 多指触摸卡死 / 包围盒历史数据报错 | 事件桥缓存的包围盒在多指场景失效 | `PointerBridge` 用 pointerId 状态机 + 单一缓存 rect,`touchcancel` 会清理指针 |
43
- | `getExtension` 返回数字而非对象 | 部分 Android 基础库 | `normalizeWebGL: true`(默认)把数值/布尔归一成对象或 `null`,并补 `drawingBufferWidth/Height` |
44
- | `instanceof HTMLCanvasElement` 为 false | wx canvas 不是 DOM 类实例 | `Symbol.hasInstance` + `WeakSet` 注册表 |
45
- | 用 `new Proxy(canvas)` 后渲染异常 | 微信内部 WeakMap 按对象身份校验 | **禁止** Proxy / 克隆 / 改原型,只 `defineProperty`(ADR-0004) |
46
- | 重复调用 `wx.createCanvas()` 导致黑屏 | 第二个画布是离屏的,不显示 | `getScreenCanvas()` 缓存;额外画布一律走 `createOffscreenCanvas` / `runtime.createCanvas()` |
47
- | WebGPU 相关 API 报错 | 小游戏无 WebGPU | 插件 `webgpu` 策略;默认告警 |
48
- | three 版本升级后控件失效 | r170+ 用 `three/addons/`,`outputColorSpace` 取代 `outputEncoding` | 示例与 `rendererHints` 使用新 API;插件 include 覆盖两种路径 |
49
-
50
- 深度缓冲补丁(应用层显式启用):
51
-
52
- ```ts
53
- renderer.setAnimationLoop(() => {
54
- renderer.render(scene, camera);
55
- // 仅当遇到 PMREM / 后处理黑屏时开启,会有额外开销
56
- if (needsDepthWorkaround) renderer.clearDepth();
57
- });
58
- ```
59
-
60
- ## 6.4 尺寸 / DPR / 安全区
61
-
62
- - `windowInfo.pixelRatio = min(rawPixelRatio, pixelRatioCap)`,默认上限 2(避免 3~4 倍 DPR 造成 GPU 压力)。
63
- - `runtime.on('resize', ...)` 里同步更新 `camera.aspect`、`renderer.setSize(w, h, false)`、`renderer.setPixelRatio(...)`。
64
- - 小程序里 `getCanvasRect()` 通过 `createSelectorQuery().fields({node, rect, size})` 异步获取;`runtime.resize()` 会重新查询并更新事件桥的 rect 缓存。
65
- - 若基础库没有 `wx.onWindowResize`,`WindowInfoStore` 会告警,业务需主动 `await runtime.resize()`。
66
- - `safeArea` 在 `WindowInfo.safeArea` 中透出(若平台提供)。
67
-
68
- ## 6.5 包体、分包与高性能模式
69
-
70
- - 官方文档标注单个主包/分包 ≤ 4MB、总包 ≤ 8MB(**以控制台当前额度为准**)。
71
- - three 本体建议用 `manualChunks` 拆成独立 chunk 并放入分包;示例见 [`examples/wechat-minigame/vite.config.ts`](../examples/wechat-minigame/vite.config.ts)。
72
- - `mini-three-assets.json` 会给出 `game.json` 建议:worker 目录设为 `{ path: 'assets/three', isSubpackage: true }`,并在创建 Worker 前调用 `wx.preDownloadSubpackage({ packageType: 'workers' })`。
73
- - `.wasm.br` + Brotli 是官方推荐的减包手段。
74
- - iOS 高性能模式(`iOSHighPerformance: true`)下内存限制更严,代码分包基本是必须的;高性能+(`iOSHighPerformance+: true`)把渲染移回微信进程,官方明确建议使用 WebGL2 且内存压力大的游戏开启,开启后需验证进程内存、渲染兼容性与帧耗时。
75
-
76
- ## 6.6 能力探测与降级
77
-
78
- `runtime.report()` 输出:
79
-
80
- ```
81
- mini-three-adapter capability report
82
- platform : wechat-game
83
- baseLibraryVersion : unknown
84
- WebGL2 / WebGL1 : true / true
85
- offscreenCanvas : true
86
- worker / wasm : false / true (brotli: true)
87
- nativeImage : true
88
- triggerGC : true
89
- getWindowInfo : true (resize events: true)
90
- ```
91
-
92
- - `probeContext()` 用 `wx.createOffscreenCanvas({type:'webgl2'})` 探测并主动 `WEBGL_lose_context` 释放,**不会**占用上屏画布。
93
- - 探测结果可用 `capabilities` 选项覆盖(用于测试或已知机型分级)。
94
- - `webgl2: false` 时会告警,但**不会静默降级到 WebGL1**——three ≥ r163 本来就要求 WebGL2,静默降级只会延后报错。
95
- - `wx.createImage` 不存在时回退 `OffscreenCanvas.createImage()`;`triggerGC` 存在与否会影响 image 创建路径的选择。
96
-
97
- ## 6.7 诊断命令 / 日志
98
-
99
- ```ts
100
- const runtime = await createWeChatGameRuntime({
101
- logLevel: 'debug',
102
- reporter: (level, message, payload) => myLogger(level, message, payload),
103
- });
104
- console.log(runtime.report());
105
- runtime.on('contextlost', () => console.warn('WebGL context lost, rebuild resources'));
106
- ```
107
-
108
- `warnOnce(key, ...)` 保证每帧的重复问题只报一次;`plugin.api.report()` 给出构建期统计。
1
+ # 06 · 微信小游戏平台差异、已知坑与诊断
2
+
3
+ > 平台规范:[微信开放文档 · Adapter](https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html)、[渲染](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/render.html)、[WXWebAssembly](https://developers.weixin.qq.com/minigame/dev/guide/performance/perf-webassembly.html)、[iOS 高性能模式](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/iOSOptimization.html),以及小游戏配置(game.json)说明。
4
+
5
+ ## 6.1 运行时基本事实
6
+
7
+ | 事实 | 对本适配层的约束 |
8
+ | --- | --- |
9
+ | iOS = JavaScriptCore,Android = V8;**无 DOM/BOM**,无全局 `document`/`window` | 必须由 `MiniThreeScope` 提供 shim |
10
+ | 基础库不附带 DOM 兼容层,需由应用自行引入 | 适配层不假设宿主已存在任何兼容对象 |
11
+ | 首次 `wx.createCanvas()` 得到唯一**上屏画布**,后续均为离屏 | `getScreenCanvas()` 必须只调用一次并缓存;能力探测只能用 `createOffscreenCanvas` |
12
+ | `Canvas.getContext('webgl2')` 返回标准 WebGL2 上下文 | three ≥ r163 需要 WebGL2;默认 `defaultContextType: 'webgl2'` |
13
+ | `wx.setPreferredFramesPerSecond` 可锁帧 | `createWeChatGameRuntime({ preferredFps })` |
14
+ | 基础库 2.13.0+ `WXWebAssembly`,2.15.0+ Worker 内可用;支持 `.wasm` / `.wasm.br` | 插件 `brotli` 选项、资产分包 |
15
+ | Worker 并发上限 **1**,目录只能放 JS,分包需先 `preDownloadSubpackage` | 所有 worker/wasm 输出到一个 `outputDir` |
16
+ | iOS 高性能+ 建议用于 WebGL2 / 内存压力大的游戏 | `game.json` 的 `iOSHighPerformance+`;见 §6.5 |
17
+
18
+ ## 6.2 导入顺序(最容易踩的坑)
19
+
20
+ ESM 静态导入会在模块体执行之前求值。若入口文件顶部写了 `import * as THREE from 'three'`,而 `createRuntime()` 在下面才执行,则 three 模块初始化期间读到的仍是占位作用域。
21
+
22
+ **推荐**:入口只导入适配层,用动态 import 加载场景:
23
+
24
+ ```ts
25
+ import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
26
+ const runtime = await createWeChatGameRuntime();
27
+ const { startScene } = await import('./scene.js'); // scene.js 里才 import three
28
+ ```
29
+
30
+ **兜底**:`createWeChatGameRuntime({ installGlobals: true })`,把 shim 显式挂到 `globalThis`(可逆),适合无法改导入结构的老项目。
31
+
32
+ 诊断:占位作用域在真正取属性时会抛
33
+ `Scoped global "xxx" was read before a runtime was created`,直接提示上述两种解法。
34
+
35
+ ## 6.3 已知坑位与处理
36
+
37
+ | 症状 | 原因 | 本项目处理 |
38
+ | --- | --- | --- |
39
+ | `createImageBitmap` 相关报错 | PC 小程序提供了该函数却没有原生 `Blob` | `scope.createImageBitmap = undefined`,插件 `forceUndef` 保证 three 走降级分支 |
40
+ | `PMREMGenerator.fromScene` 返回纯黑贴图 | 部分设备 WebGL 深度缓冲未清除 | 不在运行时改写 `WebGLRenderer.render`。应用层按需:每次 render 后 `renderer.clearDepth()`,或配置 `renderer.autoClearDepth`。见下方代码 |
41
+ | 开发者工具报 `Unexpected token` | `node_modules` 里用了较新语法 | 构建 `target: 'es2019'`(消除 `?.` / `??`);必要时开发者工具开启「将 JS 编译成 ES5」或加 Babel |
42
+ | 多指触摸卡死 / 包围盒历史数据报错 | 事件桥缓存的包围盒在多指场景失效 | `PointerBridge` 用 pointerId 状态机 + 单一缓存 rect,`touchcancel` 会清理指针 |
43
+ | `getExtension` 返回数字而非对象 | 部分 Android 基础库 | `normalizeWebGL: true`(默认)把数值/布尔归一成对象或 `null`,并补 `drawingBufferWidth/Height` |
44
+ | `instanceof HTMLCanvasElement` 为 false | wx canvas 不是 DOM 类实例 | `Symbol.hasInstance` + `WeakSet` 注册表 |
45
+ | 用 `new Proxy(canvas)` 后渲染异常 | 微信内部 WeakMap 按对象身份校验 | **禁止** Proxy / 克隆 / 改原型,只 `defineProperty`(ADR-0004) |
46
+ | 重复调用 `wx.createCanvas()` 导致黑屏 | 第二个画布是离屏的,不显示 | `getScreenCanvas()` 缓存;额外画布一律走 `createOffscreenCanvas` / `runtime.createCanvas()` |
47
+ | WebGPU 相关 API 报错 | 小游戏无 WebGPU | 插件 `webgpu` 策略;默认告警 |
48
+ | three 版本升级后控件失效 | r170+ 用 `three/addons/`,`outputColorSpace` 取代 `outputEncoding` | 示例与 `rendererHints` 使用新 API;插件 include 覆盖两种路径 |
49
+ | `img.onload` / `addEventListener('load')` 永不触发,纹理靠超时兜底 | 图片 shim 只建了「合成事件 → 用户回调」这条边,没有「原生 load → 合成事件」 | `createImageFactory` 在 patch 前抓原生 `onload`/`onerror` 描述符并挂转发器;宿主不可拦截时 `warnOnce` 告警(`image has no writable onload/onerror`) |
50
+ | `canvas.onpointerdown = fn` 之类行内处理器不触发 | 事件方法被绑定到内部对象,`this['on'+type]` 查找落空 | `patchEventTarget` 把宿主对象作为行内处理器宿主传入 |
51
+
52
+ 深度缓冲补丁(应用层显式启用):
53
+
54
+ ```ts
55
+ renderer.setAnimationLoop(() => {
56
+ renderer.render(scene, camera);
57
+ // 仅当遇到 PMREM / 后处理黑屏时开启,会有额外开销
58
+ if (needsDepthWorkaround) renderer.clearDepth();
59
+ });
60
+ ```
61
+
62
+ ## 6.4 尺寸 / DPR / 安全区
63
+
64
+ - `windowInfo.pixelRatio = min(rawPixelRatio, pixelRatioCap)`,默认上限 2(避免 3~4 倍 DPR 造成 GPU 压力)。
65
+ - `runtime.on('resize', ...)` 里同步更新 `camera.aspect`、`renderer.setSize(w, h, false)`、`renderer.setPixelRatio(...)`。
66
+ - 小程序里 `getCanvasRect()` 通过 `createSelectorQuery().fields({node, rect, size})` 异步获取;`runtime.resize()` 会重新查询并更新事件桥的 rect 缓存。
67
+ - 若基础库没有 `wx.onWindowResize`,`WindowInfoStore` 会告警,业务需主动 `await runtime.resize()`。
68
+ - `safeArea` 在 `WindowInfo.safeArea` 中透出(若平台提供)。
69
+
70
+ ## 6.5 包体、分包与高性能模式
71
+
72
+ - 官方文档标注单个主包/分包 ≤ 4MB、总包 ≤ 8MB(**以控制台当前额度为准**)。
73
+ - three 本体建议用 `manualChunks` 拆成独立 chunk 并放入分包;示例见 [`examples/wechat-minigame/vite.config.ts`](../examples/wechat-minigame/vite.config.ts)。
74
+ - `mini-three-assets.json` 会给出 `game.json` 建议:worker 目录设为 `{ path: 'assets/three', isSubpackage: true }`,并在创建 Worker 前调用 `wx.preDownloadSubpackage({ packageType: 'workers' })`。
75
+ - `.wasm.br` + Brotli 是官方推荐的减包手段。
76
+ - iOS 高性能模式(`iOSHighPerformance: true`)下内存限制更严,代码分包基本是必须的;高性能+(`iOSHighPerformance+: true`)把渲染移回微信进程,官方明确建议使用 WebGL2 且内存压力大的游戏开启,开启后需验证进程内存、渲染兼容性与帧耗时。
77
+
78
+ ## 6.6 能力探测与降级
79
+
80
+ `runtime.report()` 输出:
81
+
82
+ ```
83
+ mini-three-adapter capability report
84
+ platform : wechat-game
85
+ baseLibraryVersion : unknown
86
+ WebGL2 / WebGL1 : true / true
87
+ WebGL2 source : probe
88
+ offscreenCanvas : true
89
+ worker / wasm : false / true (brotli: true)
90
+ nativeImage : true
91
+ triggerGC : true
92
+ getWindowInfo : true (resize events: true)
93
+ ```
94
+
95
+ - `probeContext()` 优先用 `wx.createOffscreenCanvas({type:'webgl2'})` 探测并主动 `WEBGL_lose_context` 释放,**不会**占用上屏画布。
96
+ - 离屏不可用(或离屏不支持 WebGL2)时,小游戏绑定会回退到**第二次** `wx.createCanvas()` 实测——此时上屏画布已解析,新画布必然离屏。小程序绑定不做这个回退:它的画布节点来自选择器查询,直接探测会用默认属性抢先创建真实上下文。决策见 [ADR-0007](./adr/0007-capability-probe-fallback.md)。
97
+ - 两者都无法判定时返回 `undefined`,`webgl2` 按基础库版本推断,`webgl2Source` 标为 `'inferred'` 并告警一次。**「探测不到」不等于「不支持」**。
98
+ - 探测结果可用 `capabilities` 选项覆盖(用于测试或已知机型分级),此时 `webgl2Source` 为 `'override'`。
99
+ - 实测 `webgl2: false` 时会告警,但**不会静默降级到 WebGL1**——three ≥ r163 本来就要求 WebGL2,静默降级只会延后报错。
100
+ - `wx.createImage` 不存在时回退 `OffscreenCanvas.createImage()`;`triggerGC` 存在与否会影响 image 创建路径的选择。
101
+
102
+ ## 6.7 诊断命令 / 日志
103
+
104
+ ```ts
105
+ const runtime = await createWeChatGameRuntime({
106
+ logLevel: 'debug',
107
+ reporter: (level, message, payload) => myLogger(level, message, payload),
108
+ });
109
+ console.log(runtime.report());
110
+ runtime.on('contextlost', () => console.warn('WebGL context lost, rebuild resources'));
111
+ ```
112
+
113
+ `warnOnce(key, ...)` 保证每帧的重复问题只报一次;`plugin.api.report()` 给出构建期统计。
@@ -209,3 +209,16 @@ Page({
209
209
  - [ ] 构建报告 `plugin.api.report()` 中 `parseFailures` 为空、`webgpuWarnings` 已确认。
210
210
  - [ ] 真机验证 WebGL2 出图、多指触摸、横竖屏切换、前后台恢复。
211
211
  - [ ] 保存 `runtime.report()` 能力报告,登记到 [`docs/11-compat-matrix.md`](./11-compat-matrix.md)。
212
+
213
+ ## 7.9 常见报错对照
214
+
215
+ 出现下面的文案时,基本可以按下表直接定位,不必从业务代码查起。
216
+
217
+ | 报错 / 现象 | 根因 | 处理 |
218
+ | --- | --- | --- |
219
+ | `Uncaught TypeError: Class constructor xxx cannot be invoked without 'new'`,栈顶在 `GLTFLoader.js` 的 `new TextDecoder()` 处 | 构建期把 `new TextDecoder()` 改成了 `(new __m3()).TextDecoder()` | 升级适配层;临时规避见 [`docs/05` §5.7](./05-build-plugin.md#57-调试构建问题) |
220
+ | `SyntaxError: Unexpected token '.'`,产物里出现 `{ __m3().xxx }` | 对象简写属性被原地替换 | 同上 |
221
+ | 纹理永远加载不出来、`ImageLoader` 卡满超时;`img.onload` 与 `addEventListener('load')` 都不触发 | 图片 shim 没有把原生 `onload` 桥接到合成事件 | 升级适配层;日志里出现 `image has no writable onload/onerror` 说明宿主图片对象不可拦截 |
222
+ | `capabilities.webgl2 === false`,但 `#version 300 es` 能正常渲染 | 能力探测用了离屏画布,离屏与上屏能力不同 | 看 `capabilities.webgl2Source`:`'inferred'` 表示未实测;需要以实测为准时显式传 `capabilities: { webgl2: true }` |
223
+ | `Scoped global "document" was read before a runtime was created` | 在 `createXxxRuntime()` 之前求值了读 `document` 的模块 | 改为动态 `import()`;若是 `typeof document` 特性检测,升级后不会再抛 |
224
+ | 触摸事件收不到 | 小程序未转发 `bindtouch*`,或小游戏在 runtime 之后才注册监听 | 见 [`docs/06`](./06-platform-notes.md) 与 §7.5 |