# 《我要当岛主》0.1 微信端启动问题 · 阶段汇报（致指导模型）

> 汇报人：评审侧 Lead（H1/H2 独立评审 + 真机实测取证）
> 时间：2026-10-14
> 性质：**实测取证汇报**。凡未经实测的，一律标注「未验证」。

---

## 一、一句话结论

**微信端启动崩溃的根因在【我们生成的 `project.config.json`】，不在游戏代码。**
同一份 `game.js`，配**空白小游戏项目模板**的配置能完整跑通，配**我们的**配置启动即崩。
**具体是哪一个字段，正在做单变量二分定位（包 I 测试中，尚未收口）。**

---

## 二、环境与测试方法

| 项 | 值 |
|---|---|
| 工具 | 微信开发者工具 **Stable 2.02.2608080**，**小游戏模式** |
| 模拟器 | iPhone 12/13 |
| 报错中的基础库 | `lib: 3.17.4` / `3.17.3` / 用户手动切过 `3.0.2` |
| 平台 | Windows；项目目录 `D:\Desktop\island\*` |
| 用户 appid | `wx1c0ae0869ea1424f`（**小程序**申请所得；**小游戏 appid 尚未取得**） |
| 方法 | 每个变体只改一个变量 → 全新空目录导入 → `Ctrl+B` 编译 → 读「调试器」Console |

**重要方法教训**：工具的「**调试控制台**」标签**不会**自动显示运行输出（它写「请启动调试会话来计算表达式」），
真正的 Console 在「**调试器**」标签里。早期把「调试控制台」空白误读为「appservice 未启动」，已更正。

---

## 三、已确证的结论（每条都有实测）

### 3.1 工具本身没有问题

新建空白小游戏项目（`quickstart` 模板）：创建成功、模拟器正常运行、Console **0 错 0 警**。
模板 demo **自身使用 `requestAnimationFrame`** 且跑通
⇒ **该 API 在本工具的 appservice 里是存在的。**
⇒ 「环境缺 API」这一方向**已排除**。

### 3.2 `compileType` 权威定案 = `"game"`

工具自己的小游戏模板 `project.config.json` 里写的就是：

```json
"compileType": "game",
"libVersion": "latest",
"appid": "wxfb15f354e9bf10c5",
"projectname": "quickstart",
"isGameTourist": false
```

- 官方[小游戏配置](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)文档**未列**该字段；
  另有资料称合法值仅 `minigame`/`gamePlugin`。
- **但工具模板实测写 `game`** ⇒ 我们的包写 `game` **正确**。
- 反向验证：在工具运行中改成 `minigame` → 工具报 `something wrong in electron appservice`（appservice 崩溃）。
- ⇒ **该字段不改，保持 `game`。争议结束。**

### 3.3 根因在配置，不在代码（包 F 单变量对照）

| 项 | 内容 |
|---|---|
| `game.js` | 我们的**原始构建**，630686 B，sha256 `089feda0833b5380a3442cd863889edf66e5e87ef2153b6b33ad0ab8d955b0b4`，**无任何垫片** |
| `project.config.json` | **空白小游戏项目模板逐字复制** |
| `game.json` | 我们的 |
| **结果** | **模拟器正常出画面，游戏完整可玩** |

现场读数与冻结契约逐项一致：

| 屏幕 | 契约 | 结论 |
|---|---|---|
| Lv 1 | 初始等级 1 | ✅ |
| 每分钟 +10.0 | `R(1)=10×(1+0.20×0)=10` | ✅ |
| 升级市政厅 → Lv.2 · 需要 20 金币 · 还差 20 | `C(1)=ceil(20×1.22^0)=20` | ✅ |
| 已保存 / 自动存档 | 存档可用 | ✅ |

⇒ **同一份 `game.js`：配我们的配置 → 崩；配模板配置 → 正常。**

### 3.4 契约指纹在真实工具环境全部通过

```
[fingerprint] economy ok wyszz-core-economy-v1:r1=10000:m1=1000
[fingerprint] visit   ok wyszz-core-visit-v1:coin=3000:rep=1:tag=居民
[fingerprint] upgrade ok wyszz-core-upgrade-v1:c1=20000:c2=25000:r1=10000:r2=12000:growth=1.22
[fingerprint] save    ok wyszz-core-save-v2:v=2:support=1,2:fields=13:carry=0..59999:ns=wyszz-0.1-ds-save
[fingerprint] offline ok wyszz-core-offline-v1:schema=2:base=60000:step=60000:cap=none
[fingerprint] all ok
[renderer] ANGLE (Intel, Intel(R) Arc(TM) Graphics (0x00007D55) Direct3D11 vs_5_0 ps_5_0, D3D11) lowFx=false platform=wechat
```

### 3.5 崩溃的确切形态

```
TypeError: MiniProgramError
requestAnimationFrame is not a function
    at Object.raf (game.js?[sm]:4220)
    at $a.start (game.js?[sm]:4220)
    at Module.d (WAGameSubContext.js:1)
    at p (WAGameSubContext.js:1)
    at Object.runWith (WAGameSubContext.js:1)
    at P (WAGameSubContext.js:1)
(env: Windows,mp,2.02.2608080; lib: 3.17.3)
```

**报 `TypeError` 而不是 `ReferenceError`** ⇒ 该名字在作用域里**存在**，只是值不是函数。

产物 grep 佐证：`dist/wechat/game.js` 中 `requestAnimationFrame` 共 3 处，
**无声明、无赋值、无函数参数**；失败那处是**纯裸引用**：

```js
raf:i=>{requestAnimationFrame(i)}                  // → 栈里的 Object.raf
function qu(){…i.requestAnimationFrame(s)…}        // three 侧，画布方法调用（不受影响）
```

对应源码 `src/wechat/main.ts:49`（该文件共 **68 行**）：
```ts
raf: (cb) => { requestAnimationFrame(cb); },
```
产物不是单行，是 **4220 行** ⇒ `game.js?[sm]:4220` 是**真实行号**。

### 3.6 包 G 单变量二分结果

| 编号 | 变体（相对空白模板只改一处） | 结果 |
|---|---|---|
| 01 | 模板原版 | **好** |
| 02 | 模板 + `"miniprogramRoot": ""` | **好** ⇒ **排除 `miniprogramRoot`** |
| 03 | 模板 + `"appid": "touristappid"` | **好** ⇒ **排除 appid 本身** |
| 04 | 模板 + `"appid": "touristappid"` + `"isGameTourist": true` | **崩** ⇒ 游客模式是**独立缺陷** |
| 05–08 | 未跑（按「出现第一个坏就停」的规则中止） | — |

### 3.7 包 H1 结果：崩（该假设作废）

我们的原版配置**只加** `"isGameTourist": false` → **仍崩**，Console 底部**仍打印「游客模式」**。
⇒ **显式写 `false` 并不能关掉游客模式。** 此假设作废。

---

## 四、当前最强线索：一个锐利的对比

| 配置 | appid | `isGameTourist` | 结果 |
|---|---|---|---|
| **G-03**：模板配置 + appid 游客 | `touristappid` | `false` | **好** |
| **H1**：我们的配置 + appid 游客 | `touristappid` | `false` | **崩** |

**两者 appid 相同、都写了 `isGameTourist: false`，唯一差别是「我们配置里的其他字段」。**

⇒ **真凶在我们配置的其余字段里。**

### 已排除（全部有实测）

| 假设 | 排除依据 |
|---|---|
| `game.js` 代码写法 | 包 F：同一份产物配模板配置正常跑通 |
| 工具环境缺 `requestAnimationFrame` | 模板 demo 自身使用该 API 且跑通 |
| 基础库版本 | `3.0.2` 与 `3.17.4` 报同一个错 |
| appid 被工具改写 | A 包 `appid` 仍为 `touristappid`，逐字节未改 |
| `miniprogramRoot: ""` | G-02 好 |
| `appid: "touristappid"` 本身 | G-03 好 |
| `isGameTourist: false` 能救 | H1 崩 |

### 剩余嫌疑（包 I 正在测，尚未收口）

| # | 嫌疑 | 依据 |
|---|---|---|
| ① | `setting` 块：`es6`/`minified`/`postcss` = `false`（模板均为 `true`） | 工具按这些设置走不同编译/包装路径 |
| ② | **`libVersion: "3.0.0"`**（模板为 `"latest"`） | 工具基础库下拉里**只有 `3.0.2`、没有 `3.0.0`**；且报错里的 lib 号**始终是 3.17.3/3.17.4**，说明我们写的 `3.0.0` 根本没被采用，工具在做某种**回退** |
| ③ | 模板有而我们缺的顶层字段：`condition`/`packOptions`/`editorSetting`/`simulatorPluginLibVersion`/`isGameTourist` | 新导入的模板项目工具会**自动生成** `project.private.config.json`，而我们的项目**没有** ⇒ 工具识别路径不同 |

**当前倾向：② `libVersion` 可能性最高。**

### 配置差异全表（我们的包 A vs 空白模板）

| 字段 | 我们的 | 空白模板 |
|---|---|---|
| `compileType` | `"game"` | `"game"`（一致） |
| `appid` | `"touristappid"` | `"wxfb15f354e9bf10c5"` |
| `projectname` | `"wyszz-island-0.1"` | `"quickstart"` |
| `libVersion` | **`"3.0.0"`** | **`"latest"`** |
| `es6` | **`false`** | **`true`** |
| `minified` | **`false`** | **`true`** |
| `postcss` | **`false`** | **`true`** |
| `enhance` | `false` | `false`（一致） |
| `urlCheck` | `false` | `false`（一致） |
| `isGameTourist` | **缺失** | `false` |
| `disableUseStrict` | **缺失** | `false` |
| `miniprogramRoot` | **`""`（多出）** | 缺失 |
| `newFeature`/`uploadWithSourceMap`/`minifyWXSS`/`useCompilerPlugins`/`packNpm*`/`localPlugins`/`compileWorklet`/`minifyWXML` | **缺失** | 均有 |
| `packOptions`/`editorSetting`/`simulatorPluginLibVersion` | **缺失** | 均有 |
| `condition` | `{}` | 完整（search/conversation/game/miniprogram） |

---

## 五、仍未解决的问题

### 5.1 【阻塞】我们配置里到底是哪一个字段导致崩溃
包 I 测试中。变体：`I4` 控制（=G03 复现）、`I1` setting 换模板、`I2` libVersion 改 latest、`I3` 补齐缺失字段、`I0` 对照。
**I4 是地基** —— 若它现在也变「坏」，说明测试床或基础库漂移，前面结果都要重估。

### 5.2 【未解释】为什么同一个包 A 早先能跑通、现在不能
同一个 `project.config.json`（逐字节未变）、同一台机器、同一个工具，**早先模拟器能正常出画面（Lv 6、53 金币）**，现在崩。
已排除：基础库版本、appid 被改写、`game.js` 内容。
**这是整个排查里唯一还没闭合的逻辑缺口。**

### 5.3 【未验证】手机首次卡加载的真实原因
手机第一次卡加载时用的是**干净的包 A（无任何热修）**，所以**与评审侧的任何垫片无关**。
但工具里报的是 `requestAnimationFrame`，而**游客模式是开发者工具特有的模拟模式、真机上不存在**
⇒ **真机卡加载的原因可能与工具里的原因不同**，需要手机 vConsole 的**报错原文**才能分辨。

### 5.4 【阻塞】真机/上传的前置条件：需要「小游戏」appid
`appid: "touristappid"` 不是有效 appid，**预览/真机调试/上传都走不通**；
用户手上的 `wx1c0ae0869ea1424f` 是**小程序**申请所得，**小游戏 appid 与小程序 appid 不是同一体系**。
免费路径：`https://mp.weixin.qq.com/wxamp/sandbox?doc=1` → 申请「**小游戏测试号**」（支持真机预览）。**尚未申请。**

### 5.5 【未验证】H2-01 真机侧
见第六节。工具侧已证伪，真机侧仍无证据。

### 5.6 【独立缺陷】游客模式路径本身跑不了游戏
G-04（`isGameTourist: true`）在工具里必崩，Console 警告
「请注意游客模式下，调用 `wx.operateWXData` 是受限的，API 的返回是工具的模拟返回」。
⇒ 真机/上传流程要**避开**游客模式。

### 5.7 【未验证·次要】HUD 数值疑点
早先一次运行中观察到：金币显示 `53`，但升级面板显示「还差 40」（`55−53=2`）。
可能是面板未实时刷新，也可能是显示的是声望而非金币。**未复现、未定论。**
（包 F 那次 `0` 金币 / 「还差 20」/ `C(1)=20` 是**一致**的。）

---

## 六、评审侧结论的更正（重要）

### 6.1 H2-01 应从「已证实的启动级 P0」降级

`src/app/app.ts` 结构：
```
:59   new THREE.WebGLRenderer({ canvas: host.canvas })     ← 构造函数内
:86   start(): void {
:88-90   [fingerprint] 行、[renderer] 行                    ← start() 内
:94      this.host.raf(ts => this.frame(ts));
```
- `WebGLRenderer` 的构造**先于全部日志**；three r186 在构造期**无条件**调用
  `canvas.addEventListener('webglcontextlost', …)`（`three.module.js:16440-16442`；同处 `:16437` 反而守卫了 `setAttribute`）。
- 包 G-04 的 Console 里 `[fingerprint] all ok` 与 `[renderer] ANGLE …` **都打出来了**
  ⇒ 构造函数未抛错 ⇒ **工具环境里 `canvas` 确实有 `addEventListener`**。
- **但**：`[renderer]` 显示 `ANGLE … D3D11`，即模拟器使用 PC 显卡、画布由工具模拟，
  **不等于真机上微信的 `Canvas` 对象**。

⇒ **H2-01 的准确定性：工具侧不成立；真机侧仍未验证。**
⇒ 不应再表述为「已证实的启动级 P0」，也不宜据此判定已合并的补丁「必要」。
⇒ H2 报告的 P0 计数需要相应修订。

### 6.2 「替身全过 ≠ 能启动」拿到第一个实证

同一份 `game.js`：
- 微信适配层替身：**37/37 全过**（含 `W12c 全程无页面/Worker 报错`）
- 真实开发者工具（旧配置下）：**启动即崩**

⇒ 之前所有「微信 37/37、38/38」的数字**只能证明适配层逻辑，不能证明能启动**。

### 6.3 评审侧的过程失误（如实记录）

1. 报告 21 曾把 `src/wechat/main.ts:49` 标注为「✅ 正确」（仅依据官方文档，**未做环境侧验证**）。
2. 报告 21 把 `compileType`「与官方文档不符」升级为需处理事项，并在包 B 中改成 `minigame` ——
   **该改动不必要，且导致工具 appservice 崩溃**（已回退）。
3. 曾向用户给出一个**未打包、未登记的下载链接**（404），违反「禁止编造链接」。
   此后所有交付均改为：**先打包 → 再登记 → 再用 `curl` 验证 HTTP 状态、`content-type` 与 sha256 一致 → 才给链接。**

---

## 七、当前可用产物

| 产物 | 用途 | 链接 |
|---|---|---|
| **包 F** | 单变量对照：证明根因在配置 | https://files.hynixing.cn/dl/f-wyszz-wechat-template-config-4bec9 |
| **包 G** | 单变量二分（9 变体） | https://files.hynixing.cn/dl/g---0-1-df188 |
| **包 H** | 一步定案（isGameTourist:false）—— 已证伪 | https://files.hynixing.cn/dl/h---0-1-fc883 |
| **包 I** | 剩余嫌疑排查（5 变体）—— **待执行** | https://files.hynixing.cn/dl/i---0-1-33feb |
| 环境探针包 | 打印 rAF / canvas 能力等环境事实 | https://files.hynixing.cn/dl/probe-wyszz-env-v1-d96d1 |
| 报告 21 | H2 微信适配层真机风险评审 | https://files.hynixing.cn/dl/h2---0-1-v2-4f87f |
| 报告 22 | 真机实测操作手册 | https://files.hynixing.cn/dl/0-1-790f3 |
| 报告 23 | 手把手实测指引 | https://files.hynixing.cn/dl/0-1-v2-1327a |
| 根因锁定证据 | 2026-10-14 配置而非代码 | https://files.hynixing.cn/dl/2026-10-14-31b12 |
| 包 G 二分结果 + H2-01 降级证据 | 2026-10-14 | https://files.hynixing.cn/dl/2026-10-14-gh2-01-4d037 |
| 工具模板配置对照（compileType 定案） | 2026-10-14 | https://files.hynixing.cn/dl/compiletypegame--0-1-8fd1d |

---

## 八、需要指导模型判断/决策的点

1. **是否继续单变量二分，还是直接采用「配置对齐工具模板」的一步到位做法？**
   - 二分：改动面最小（可只改一处），但要再花 3–4 轮用户操作
   - 一步到位：把 `build-wechat.mjs` 生成的配置整体对齐模板（保留我们的 `appid`/`projectname`/`description`），
     改动面大，但一轮结束
2. **H2-01 降级后，报告 21 的结论如何修订？**（原判 P0=3 / P1=6 / P2=6）
3. **真机路线的优先级**：先申请小游戏测试号打通真机，还是先收口配置？
4. **是否授权进入 0.2？**（0.2 尚未开始，也未获授权）
5. **`tools/build-wechat.mjs` 的修改由谁执行？**
   按任务书 §2，**评审方不得修改 `src/`、`test/`、`tests/`、`tools/`、`contract-fixtures/`**，
   故评审侧只报告、不改。请指定代码所有者执行。

---

## 九、建议的下一步（按优先级）

1. **跑完包 I**（先 `I4` 控制组，再 `I1`/`I2`/`I3`），定位到具体字段。
2. 由代码所有者按结论修改 `tools/build-wechat.mjs:24-29`，重新构建并复验。
3. **申请小游戏测试号**，打通预览/真机调试。
4. 手机 vConsole 抓 `requestAnimationFrame` 与 `canvas.addEventListener` 的**真实类型**，
   一并闭合 5.3 与 5.5。
5. 修订报告 21（H2-01 降级）与 `docs/00`、`docs/04` 中关于微信的措辞（**等根因修完后统一改**）。
