# 22 · 《我要当岛主》0.1 真机实测操作手册（微信端）

- 编写：Lead ｜ 日期：**2026-10-13**
- 适用对象：`frontend-rebuild-hm-work-H2/dist/wechat/`（小游戏包：`game.js` + `game.json` + `project.config.json` + `MANIFEST.json`）
- 配套：`docs/21-H2-微信适配层真机风险评审报告.md`（结论：不通过，P0=3）

> **一句话**：真机是唯一能证伪 H2-01 的地方 —— 现在就值得测；但**大概率第一屏是黑的**，
> 而且**第一个坑可能不是黑屏，是 appid 类型不对**。下面按「会撞到的顺序」排。

---

## 第 0 步（最可能先撞到）：确认这个 appid 是「小游戏」还是「小程序」

你说的是「小程序申请下来了」，但本项目是**小游戏**（`game.json` + `wx.createCanvas` + 无 DOM）。
**小游戏与小程序是两类账号，appid 不通用。**

官方依据：[微信开发者工具更新日志](https://developers.weixin.qq.com/miniprogram/dev/devtools/uplog)（2026-10-13）里明确有一条修复记录 ——
「**将小游戏项目的 appid 直接修改成小程序的 appid 会导致模拟器消失**」。

**怎么确认（选一个）**
1. 登录 `mp.weixin.qq.com` → 看账号类型。小游戏账号后台与小程序账号后台的左侧菜单不同。
2. 直接用开发者工具导入（第 2 步），如果报「appid 与项目类型不符」/ 模拟器空白消失 → **就是类型不对**，需要去注册/开通**小游戏**账号。
3. 若确实是小程序账号：本 0.1 的小游戏包**无法用它的 appid 预览或上传**，得先有小游戏 appid。

> 这一步没过，后面全白做。**先确认它。**

---

## 第 1 步：把 `compileType` 改成 `minigame`

**本项目产物写的是 `"compileType": "game"`，而官方文档的有效值里没有 `game`。**

官方依据：[小游戏项目配置文件](https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html)（2026-10-13）——
`compileType` 的**有效值**只有两个：

| 值 | 说明 |
| --- | --- |
| `minigame` | 当前为普通小游戏项目 |
| `gamePlugin` | 当前为小游戏插件项目 |

**操作**：把 `dist/wechat/project.config.json` 里的 `"compileType": "game"` 改为 `"compileType": "minigame"`。
（若工具能正常导入并识别为小游戏，说明 `game` 被当兼容别名接受了 —— **两种结果都要记下来**，这正是 H2-07 待验证的那一项。）

---

## 第 2 步：导入项目（**appid 必须在这一步填**）

官方文档（同上，2026-10-13）明确：`appid` 与 `projectname` **「只在新建项目时读取」**。

1. 打开微信开发者工具（稳定版即可）
2. 「导入项目」
3. **目录**选：`/vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-H2/dist/wechat/`
   （**注意是 `dist/wechat/`，不是仓库根目录** —— 根目录里没有 `game.js`）
4. **AppID**：填你申请到的那个（**就是这一步**，导入后再改 `project.config.json` 无效）
5. 后端服务：选「不使用云服务」

**若已经导入过、要换 appid**：走「详情 → 基本信息 → AppID → 修改」，
它会写进 `project.private.config.json`（该文件优先级高于 `project.config.json`）。

---

## 第 3 步：先在工具模拟器里跑一遍（但别把它当结论）

模拟器能跑起来只说明「代码没语法错」。**它不能替代真机**，理由很具体：
本项目 `test/wechat-sim.mjs` 的替身 37/37 全过，恰恰是因为它用**浏览器原生 `OffscreenCanvas`**，
而原生 canvas **自带 `addEventListener` 和 WebGL2** —— 真机微信 canvas 未必有。

**看什么**：控制台有没有报错、有没有画面、能否点居民加金币。

---

## 第 4 步：真机调试 / 预览（二选一或都做）

### 4A「真机调试」（推荐 —— 能在电脑上看手机的控制台）

官方依据：[真机远程调试](https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug.html)（2026-10-13）

1. 工具栏点 **「真机调试」**（官方建议优先用 **真机调试 2.0**）
2. 工具会打包上传，就绪后弹出二维码
3. **手机微信扫码** → 手机上运行 + 电脑上出现调试窗口
4. 小游戏专属注意（同页官方说明）：
   - 小游戏远程调试**仅支持**工具 ≥ `1.02.1809260`、iOS 微信客户端 ≥ `6.7.2`、Android 微信客户端 ≥ `6.7.3`
   - 小游戏调试窗口右侧多一个 **「Contexts」** 栏，可切换不同 JS 上下文
   - **小游戏「目前尚不支持 Storage 面板」** → 想看存档得靠游戏内调试输出，别指望 Storage 面板

### 4B「预览」（最省事，但没有控制台）

工具栏点 **「预览」** → 手机扫码 → 打开的是**开发版**。
看不到 console，只能看画面。适合"先确认是不是黑屏"。

> 补充：官方还有「自动预览」，需微信客户端 ≥ 6.6.7，且**仅限与开发者工具同账号的微信**。

---

## 第 5 步（可选）：体验版，给别人测

1. 工具里「上传」→ 填版本号与备注
2. `mp.weixin.qq.com` → **版本管理** → 把刚上传的开发版设为**体验版**
3. 「成员管理」→ 添加**体验成员**（微信号）
4. 体验成员扫码即可打开

> 0.1 是游客模式产物、无真实 appid 时用的是 `touristappid`；现在有真 appid 了，上传前记得第 1、2 步已做完。

---

## 真机逐条打勾清单（照着点，别凭印象）

### A. 第一屏（**先看这里，一条就能定案**）

- [ ] **A1** 打开后是黑屏，还是有画面？
- [ ] **A2** 若是黑屏，控制台**第一条**异常原文是什么？对照下表：

| 控制台报错原文 | 对应问题 | 说明 |
| --- | --- | --- |
| `TypeError: canvas.addEventListener is not a function`（或 `removeEventListener`） | **H2-01（P0）** | 官方 Canvas 文档无此方法，three r186 无条件调用它 |
| `THREE.WebGLRenderer: Error creating WebGL context.` | **H2-02（P0）** | 该机 `getContext('webgl2')` 返回 null（three r186 不支持 WebGL1） |
| `Failed to set the 'width' property on '…Canvas'` 或尺寸为 0 | **H2-03（P0）** | `getSystemInfoSync()` 返回空对象，`Math.max(1, undefined)` = `NaN` |
| `appid 与项目类型不符` / 模拟器消失 | **第 0 步** | appid 不是小游戏类型 |

- [ ] **A3** 记下手机型号、系统版本、微信版本、基础库版本（这四项是复现的最小信息）

### B. 玩法（画面出来了才有意义）

- [ ] **B1** 点居民 → 金币 +3、声望 +1（右上角数字变化）
- [ ] **B2** 点市政厅（金币不足）→ 提示「金币不足」、等级不变、**金币一分不扣**
- [ ] **B3** 攒够 20 金币点市政厅 → 升到 Lv2，产速从 10/分 变 12/分
- [ ] **B4** 单指拖动 → 相机旋转，**且不触发寻访**（金币不变）
- [ ] **B5** 双指捏合 → 缩放，**且不触发寻访**

### C. 真机专属（模拟器测不出，必须真机）

- [ ] **C1**（H2-13）顶栏右侧的金币/等级**有没有被右上角胶囊按钮盖住**？
- [ ] **C2**（H2-06）底部「升级市政厅」按钮**有没有被全面屏 Home Indicator 压住**/ 点不准？
- [ ] **C3**（H2-04）**按住屏幕不放** → 下拉通知栏（或锁屏）→ 回前台 → 再点居民，**还点得动吗？**
      （预期风险：残留触点导致此后所有点击与拖动**全部失效**，只能重启）
- [ ] **C4**（H2-05）连续点居民 **100 次**，观察内存/帧率是否明显变差（预期风险：每次飘字新建 2 张离屏画布且不回收）
- [ ] **C5** 进后台 → 等 **1 分钟** → 回前台 → 是否弹出离线收益面板，数值是否符合 10 金币/分钟
- [ ] **C6** 重复回前台 3 次 → **不应重复发放**（面板只出一次）
- [ ] **C7**（H2-14）玩出进度 → 微信「设置 → 通用 → 存储空间」清理缓存 → 重进游戏 → 看是否回退为新游戏
- [ ] **C8** 真机上的 `wx.getSystemInfoSync()` 实际返回了什么（`windowWidth` / `windowHeight` / `pixelRatio` / 有没有 `safeArea`）

---

## 如果第一屏就是黑屏：先上热修，再继续测

`review-H2/hotfix/` 里备好了**只前置到构建产物、不改任何源文件**的热修：

```bash
cd /vol1/ai/projects/wyszz-new/frontend-rebuild-hm-work-H2
node review-H2/hotfix/apply-shim.mjs      # 应用（原 game.js 备份为 game.js.orig）
#  … 重新在开发者工具里点「真机调试」/「预览」 …
node review-H2/hotfix/apply-shim.mjs --revert   # 撤销
# 彻底还原：npm run build:wechat
```

热修做两件事（都是「缺失才补」）：
1. 给 `wx.createCanvas()` 的返回值补 `addEventListener` / `removeEventListener` 空实现 → 越过 H2-01
2. 给 `wx.getSystemInfoSync()` 的空对象/缺字段兜底（`getWindowInfo` 兜底 → 最后 375×667） → 越过 H2-03

> ⚠ 热修**未在真机验证过**，它只是让测试能越过"启动即崩"这一层、看到后面真正的问题。
> **它不构成对 H2-01 的修复方案定论**，也不代表问题已解决。

---

## 官方依据（全部查阅于 2026-10-13）

| 用途 | URL |
| --- | --- |
| 小游戏 `compileType` 有效值 | https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html |
| 真机远程调试（含小游戏专节） | https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug.html |
| 开发者工具更新日志（小游戏 appid ≠ 小程序 appid） | https://developers.weixin.qq.com/miniprogram/dev/devtools/uplog |
| 自动预览 | https://developers.weixin.qq.com/miniprogram/dev/devtools/debug.html |
| Canvas 对象成员表（无 addEventListener） | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/Canvas.html |
| `wx.createCanvas`（首次=上屏画布） | https://developers.weixin.qq.com/minigame/dev/api/render/canvas/wx.createCanvas.html |
| weapp-adapter 才模拟 `canvas.addEventListener` | https://developers.weixin.qq.com/minigame/dev/guide/runtime/adapter.html |
| WebGL2 支持情况（iOS 高性能模式） | https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform/Design/WebGL2.html |
| `getSystemInfoSync` 停止维护 / 可能返回空对象 | https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getSystemInfo.html |
| 右上角胶囊 `getMenuButtonBoundingClientRect` | https://developers.weixin.qq.com/minigame/dev/api/ui/menu/wx.getMenuButtonBoundingClientRect.html |
| 代码包上限（主包 4M / 总 30M） | https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html |
| 本地缓存（10MB、可能被系统清理） | https://developers.weixin.qq.com/minigame/dev/api/storage/wx.setStorageSync.html |

---

## 本手册明确不保证的

- **我没有真机、没有官方模拟器、没有做过上传/预览** —— 上面所有步骤都是**按官方文档推导的操作流程**，不是我实测过的记录。
- `compileType` 填 `minigame` 后工具是否接受、填 `game` 是否被当兼容别名 —— **未验证**，正是要你这次测出来。
- 热修是否真能越过 H2-01 —— **未验证**（前提是 H2-01 成立）。
- 你手上的 appid 是不是小游戏类型 —— **只有你能确认**。
