# 23 · 真机实测：从打开网页开始的手把手（照着做就行）

- 编写：Lead ｜ 日期：**2026-10-13**
- 前置阅读：`docs/22-真机实测操作手册.md`（参考手册，含全部官方依据 URL）
- 本文件是**线性步骤**，你不需要懂微信生态，从第 0 步开始照着做。

---

## 先看这张总览（30 秒）

你要做的事只有 4 件：**拿一个小游戏 AppID → 装开发者工具 → 导入我打好的包 → 手机扫码看**。

### 关键分岔：AppID 从哪来

你手上那个 appid 是「**小程序**」还是「**小游戏**」？**这两类账号的 appid 不通用。**
官方开发者工具更新日志里明确有一条修复记录 ——「将**小游戏项目的 appid 直接修改成小程序的 appid 会导致模拟器消失**」。

所以有两条路，**建议先走 A**：

| 路线 | 说明 | 耗时 |
| --- | --- | --- |
| **A（推荐）申请小游戏「测试号」** | 官方给开发者用的免审核测试账号，**支持真机预览**；不用等你那个账号，也不用管它是什么类型 | **约 3 分钟** |
| **B 用你自己申请下来的 appid** | 前提是它确实是**小游戏**类型；若是小程序类型，这个包用不了 | 取决于确认结果 |

> 官方原话（[申请测试号](https://developers.weixin.qq.com/miniprogram/dev/devtools/sandbox.html)，2026-10-13）：
> 扫码即可获得为自己分配的**小程序和小游戏测试账号**，用它「在开发者工具里创建项目做开发测试，以及**真机预览体验**」。

### 我给你的两个包（都在下面第 4 步用）

| 包 | 用途 | 说明 |
| --- | --- | --- |
| **A · 原始未改** | **第一次真机测试就用它** | 目的就是**验证 H2-01 到底是不是真的**：如果它黑屏且报 `canvas.addEventListener is not a function`，这个 P0 就当场定案 |
| **B · 加热修** | 验证完之后再用 | 越过 H2-01/H2-03 的启动崩溃，让你能看到画面、测玩法 |

> **顺序很重要**：先用 A 把问题**看到**，再用 B 绕过它继续测。别一上来就用 B —— 那样就失去了"真机到底会不会崩"这个最关键的结论。

---

## 第 0 步 · 打开第一个网页：申请小游戏测试号

1. 打开电脑上的浏览器（Chrome / Edge 都行）。
2. 地址栏输入并回车：
   **`https://mp.weixin.qq.com/wxamp/sandbox?doc=1`**
3. 页面上会出现一个**二维码**。
4. 拿起手机，打开**微信** → 右上角「**+**」→「**扫一扫**」→ 扫这个二维码。
5. 手机上点「**允许**」/「确认」。
6. 电脑页面刷新后，你会看到**分配给你的两个账号**：
   - 一个「**小程序测试号**」
   - 一个「**小游戏测试号**」← **你要的是这个**
7. **把「小游戏测试号」的那串 AppID 复制下来**（形如 `wx` 开头的一串字母数字），先粘到记事本里。
   - ⚠️ 别复制成小程序测试号那个，两个 appid 不通用。

> **顺手做（可选但有用）**：另开一个标签页打开 `https://mp.weixin.qq.com`，
> 用同一个微信扫码登录**你自己申请下来的**账号，进去后点左侧「**设置**」→「**开发设置**」，
> 页面上会显示这个账号的 **AppID**。记下它，同时注意页面上写的是「小程序」还是「小游戏」。
> 若显示的是小程序、且你更想用自己账号，那需要另外注册一个**小游戏**账号（测试号可以先让你把流程跑通）。

---

## 第 1 步 · 下载并安装「微信开发者工具」

1. 浏览器打开：
   **`https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html`**
2. 找到「**稳定版 Stable Build**」那一栏（**不要**选开发版/预发布版）。
3. 按你的电脑系统点对应的下载：
   - Windows → 一般选 **Windows 64**（`x64`）
   - Mac（M 系列芯片，Apple Silicon）→ 选 **macOS ARM64**
   - Mac（Intel 芯片）→ 选 **macOS x64**
4. 下载完成后安装（Windows 一路下一步；Mac 拖进「应用程序」）。
5. 安装完**打开它**。第一次打开会出现登录二维码。
6. **用刚才那个微信扫码登录**（建议用同一个微信，省得权限对不上）。

> 登录后如果它让你选「小程序 / 小游戏」，说明它识别到你账号下两种都有，**先不用管**，下一步导入项目时会再问你。

---

## 第 2 步 · 下载我打好的包，解压到本地

1. 下载**包 A（先用这个）**：
   **https://files.hynixing.cn/dl/a-wyszz-wechat-clean-2ba72**
2. 解压它。解压后会得到一个文件夹，里面是 4 个文件：
   ```
   wyszz-wechat-A-clean/
     ├── game.js                  ← 游戏主程序
     ├── game.json                ← 小游戏配置（入口、屏幕方向）
     ├── project.config.json      ← 项目配置（含 compileType）
     └── MANIFEST.json            ← 构建清单
   ```
3. **记住这个文件夹的完整路径**（比如 `D:\下载\wyszz-wechat-A-clean`）——下一步要用。
4. 把包 B 也下载下来备用（先不解压也行）：
   **https://files.hynixing.cn/dl/b-wyszz-wechat-hotfix-c3f0e**

> 建议解压到**路径不含中文和空格**的地方，例如 `D:\wyszz\A`，能少一类玄学报错。

---

## 第 3 步 · 在开发者工具里「导入项目」

1. 回到微信开发者工具。
2. 左侧项目列表点「**+**」（或顶部菜单「项目」→「导入项目」）。
3. **目录**：点「选择」，选中第 2 步解压出来的那个文件夹
   （`wyszz-wechat-A-clean`，**选到这一层**，不要选到里面的文件）。
4. **AppID**：粘贴第 0 步复制的**小游戏测试号 AppID**。
   - ⚠️ **这一步必须填对**。官方文档写明 appid「**只在新建项目时读取**」，导入后再去改 `project.config.json` 是**无效**的。
   - 若已导入想换：走工具右上角「**详情**」→「**基本信息**」→ AppID 那一行点「修改」。
5. **后端服务**：选「**不使用云服务**」。
6. 点「**确定**」。

**可能出现的两种情况**：
- ✅ 正常进入项目窗口，左侧出现模拟器 → 继续第 4 步。
- ❌ 报「appid 与项目类型不符」/ 模拟器一片空白甚至消失 → 说明这个 appid 不是小游戏类型，**回第 0 步换成「小游戏测试号」的 appid**。

> 关于 `compileType`：官方[小游戏项目配置文件](https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html)里有效值只有 `minigame` 和 `gamePlugin`，**没有 `game`**。
> 我给你的包 A 里保留的是原始的 `"game"`（**这是故意的** —— 正好顺便测出工具到底认不认它）。
> 如果工具报「不是小游戏项目」，把 `project.config.json` 里的 `"compileType": "game"` 改成 `"minigame"` 再重新导入。**两种结果都请记下来**，这是报告 21 里 H2-07 那一项要的答案。

---

## 第 4 步 · 先在工具里看一眼（1 分钟）

不插手机，先在电脑上看：

1. 左边**模拟器**区域：有没有出现画面（漂浮的小岛、市政厅、居民）？
2. 下方**调试器 → Console**：有没有红色报错？

**这里过了不代表真机过** —— 开发者工具的模拟器对 canvas 的支持比真机"更全"，
本项目自己的替身测试 37/37 全过，就是因为替身用的是浏览器原生画布（自带 `addEventListener`）。
**模拟器是参考，手机才是考场。**

---

## 第 5 步 · 真机测试（第一次：验证 H2-01）**← 最关键的一步**

1. 开发者工具顶部工具栏找到「**真机调试**」按钮，点它。
   - 如果弹出「真机调试 1.0 / 2.0」，**选 2.0**（官方建议优先用 2.0）。
2. 工具会开始打包上传，等它跑完。
3. 屏幕上出现一个**二维码**。
4. **手机微信扫码**（同一个微信）。
5. 手机上会自动打开你的小游戏；同时电脑上会出现一个**调试窗口**。
   - 小游戏的区别：调试窗口右侧会多一个「**Contexts**」栏，可以切换不同 JS 上下文。
   - ⚠️ 小游戏**不支持 Storage 面板**（官方明文），所以想看存档别指望这个面板。

6. **现在看手机屏幕，并盯住电脑 Console 的第一条红字** —— 对照下表：

| 手机现象 | Console 第一条报错原文 | 结论 |
| --- | --- | --- |
| 黑屏 | `TypeError: canvas.addEventListener is not a function`（或 `removeEventListener`） | **H2-01 当场定案 ✅** —— 这是本次测试最重要的结论 |
| 黑屏 | `THREE.WebGLRenderer: Error creating WebGL context.` | **H2-02** —— 这台机器没有 WebGL2 |
| 加载即失败 / 白屏 | `Failed to set the 'width' property on '…Canvas'` | **H2-03** —— `getSystemInfoSync()` 返回了空对象 |
| 有画面 | （无报错） | **H2-01 在真机上不成立** —— 说明官方 Canvas 实际有 `addEventListener`（文档没写），这同样是重要结论 |

7. **无论哪种结果，都请把这些记下来**（我可以据此更新报告）：
   - 手机型号、系统版本、微信版本
   - Console 第一条异常的**完整原文**
   - 是有画面还是黑屏

---

## 第 6 步 · 换包 B，绕过启动崩溃，继续测玩法

如果第 5 步是黑屏（大概率），那就用**包 B** 把这一层绕过去，看后面真正的问题：

1. 解压包 B，得到 `wyszz-wechat-B-hotfix/`。
2. 开发者工具里：**换一个项目目录**导入（同样填那个小游戏测试号 AppID），目录选包 B。
   - 或者更简单：把包 B 里的 4 个文件**覆盖**到包 A 那个文件夹里，工具点「**编译**」刷新即可。
3. 再点「**真机调试**」→ 扫码。
4. 这次应该能出画面了，然后按下面清单逐条测。

**包 B 做了什么**（只动构建产物，不改任何源文件）：给 `wx.createCanvas()` 的返回值补上 `addEventListener`/`removeEventListener` 空实现；给 `wx.getSystemInfoSync()` 的空对象/缺字段兜底。**它未在真机验证过**，只是让你能继续往下测。

---

## 第 7 步 · 真机逐条打勾清单

### 第一屏
- [ ] 有画面 / 还是黑屏
- [ ] 有黑屏就记录第一条异常原文

### 玩法（画面出来后才测）
- [ ] 点**居民** → 右上角金币 +3、声望 +1
- [ ] 点**市政厅**（金币不足）→ 提示不足、等级不变、**金币一分不扣**
- [ ] 攒够 20 金币点市政厅 → 升到 Lv2，产速从 10/分 变 12/分
- [ ] 单指拖动 → 相机转，**且不发奖**
- [ ] 双指捏合 → 缩放，**且不发奖**

### 只有真机才测得出的（重点）
- [ ] **顶栏右侧的金币/等级有没有被右上角「胶囊按钮」盖住？**（H2-13）
- [ ] **底部「升级市政厅」按钮有没有被全面屏底部横条压住？**（H2-06）
- [ ] **按住屏幕不放 → 下拉通知栏 → 回前台 → 再点居民，还点得动吗？**
      （H2-04：预期风险是此后**所有点击和拖动全部失效**，只能重启）
- [ ] 连续点居民 **100 次**，内存/帧率有没有明显变差（H2-05：每次飘字新建 2 张画布不回收）
- [ ] 进后台 → 等 **1 分钟** → 回前台 → 是否弹离线收益面板，数值是否约 10 金币/分钟
- [ ] 重复回前台 3 次 → **不应重复发放**
- [ ] 玩出进度 → 微信「设置 → 通用 → 存储空间」清理缓存 → 重进 → 是否回退成新游戏（H2-14）

---

## 卡住了怎么办

| 现象 | 怎么办 |
| --- | --- |
| 提示「appid 与项目类型不符」 | 第 0 步的 appid 不是小游戏类型 → 换**小游戏测试号** |
| 模拟器一片空白 / 消失 | 同上；或 `project.config.json` 的 `compileType` 需要改成 `minigame` |
| 「真机调试」点了没反应 / 一直转圈 | 换用「**预览**」按钮（扫码看开发版，但没有 Console） |
| 手机扫码后打不开 | 确认扫码的微信 = 登录开发者工具的微信；测试号也必须用申请它的那个微信 |
| 手机看不到 Console | 必须用「**真机调试**」才有电脑端 Console；「预览」没有 |
| 想彻底还原 | 包 A / 包 B 都是独立文件，删掉重下即可（原始产物 = 包 A） |

---

## 请回来告诉我的 4 件事

1. 你手上那个 appid 是**小程序**还是**小游戏**类型
2. 包 A 在真机上：**黑屏还是有画面**？Console 第一条异常原文是什么？
3. 包 B 在真机上：**画面出来了吗**？
4. 第 7 步清单里，哪几条**没通过**

有了这 4 条，我就能把报告 21 里的 P0/P1 从"推测"改成"真机实测确认"，并给出准确的修复方案。

---

## 本指南明确不保证的

- **我没有真机、没有装过官方模拟器、没有做过扫码预览** —— 上面每一步都是**按官方文档推导的操作流程**，不是我的实测记录。
- 「小游戏测试号能扫码真机预览」是官方文档的描述（[申请测试号](https://developers.weixin.qq.com/miniprogram/dev/devtools/sandbox.html)，2026-10-13），我**未验证**。
- 包 B 的热修**未在真机验证过**，前提是 H2-01 成立。
- 开发者工具的实际界面文字可能随版本略有差异（按钮位置基本稳定）。

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

| 用途 | URL |
| --- | --- |
| 申请测试号（含小游戏测试号，支持真机预览） | https://developers.weixin.qq.com/miniprogram/dev/devtools/sandbox.html |
| 开发者工具下载 | https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html |
| 真机远程调试（含小游戏专节 / Contexts / 无 Storage 面板） | https://developers.weixin.qq.com/miniprogram/dev/devtools/remote-debug.html |
| 小游戏 `compileType` 有效值 / `appid` 只在新建时读取 | https://developers.weixin.qq.com/minigame/dev/devtools/projectconfig.html |
| 获取 AppID（设置 → 开发设置） | https://developers.weixin.qq.com/miniprogram/introduction |
| 小游戏 appid ≠ 小程序 appid | https://developers.weixin.qq.com/miniprogram/dev/devtools/uplog |
