# 微信小游戏「在 Windows VM 里跑通并出真机码」完整流程与坑清单

> 版本：v2（2026-10-19 实测补全，含 G-09 / 0.2.3-pre 部署全过程）
> 适用：在 NAS 的常驻 Windows VM 里，用微信开发者工具打开小游戏工程、编译、出真机预览码
> 配套：`验收流程-开发者工具.md`（v1，偏"验收步骤"）；本文偏"部署与出码 + 踩坑实录"

---

## 0. 一句话

在无 3D 加速的 VM 里，**打包、编译、出真机预览码全都能做** ✓；
**唯一做不到的是"在虚拟机里看小游戏画面"** ✗（微信运行时校验图形能力，这块必须真机或 Web 版）。

---

## 1. 环境事实（写死，别再猜）

| 项 | 值 |
|---|---|
| VM 驱动通道 | `/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/_scripts/vmctl.py <工具名> '@PS脚本' --timeout N` |
| 开发者工具 CLI | `C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat` |
| 工具版本 | `2.02.2608080` |
| VM 内存/分辨率 | 6 GB / 1920×1080（DPI 150%）；显存适配器 `Microsoft 基本显示适配器`（QEMU `-vga std`，无 3D） |
| 宿主 → VM | 单向：VM 能连 NAS（8094/8098/8085 实测通），**NAS 连不进 VM**（user-mode NAT） |
| 回传文件 | VM 用 `Invoke-WebRequest -Uri http://192.168.1.38:8094/ -Method POST -Body $bytes -Headers @{"X-Filename"="x.png"}`；NAS 侧先起 `_scripts/vm-upload-server.py 8094` |
| 真实 appid | `wx1c0ae0869ea1424f`（**务必用它**，`touristappid` 出码会失败） |

---

## 2. 标准流程（本次实测走完，8 步）

### ① 校验交付包（拿到别人的包先验 sha256）

```bash
Z="/vol1/ai/projects/wyszz-new/frontend-rebuild-hm/tasks-out/G-09/叫我大岛主-0.2.3-pre-微信-正式包.zip"
sha256sum "$Z"    # 与交付报告里的值逐字比对（本次 601a6bbc… 完全一致 ✓）
unzip -l "$Z"     # 期望：MANIFEST.json / project.config.json / game.js / game.json 四件在根目录
```

### ② 换成真实 appid（G-09 的包是 `touristappid`，必须改）

```python
cfg = json.load(open("project.config.json", encoding="utf-8"))
cfg["appid"] = "wx1c0ae0869ea1424f"      # 关键一步
json.dump(cfg, open("project.config.json","w",encoding="utf-8"), ensure_ascii=False, indent=2)
# 同步更新 MANIFEST.json 里 project.config.json 的 sha256，保持包内自洽
```

### ③ 重新打包并下发

```bash
cd /tmp/g09x && zip -q /tmp/g09-serve/g09-wechat-023.zip ./*     # 文件保持根目录
cd /tmp/g09-serve && python3 -m http.server 8098 --bind 0.0.0.0  # VM 侧来拉
```

### ④ VM 里下载 + 解包

```powershell
Invoke-WebRequest -Uri "http://192.168.1.38:8098/g09-wechat-023.zip" -OutFile C:\wyszz\g09.zip -TimeoutSec 120
Expand-Archive -Path C:\wyszz\g09.zip -DestinationPath C:\wyszz\wechat023 -Force
```

### ⑤ 打开工程

```powershell
& $cli open --project C:\wyszz\wechat023      # 成功标志：出现 "√ open"，窗口标题变成项目名
```
> 判定成功的**可靠信号**是窗口标题变成 `wyszz-island-0.2.3-pre`，**不是**退出码（见坑 7）。

### ⑥ 编译 + 出真机预览码

```powershell
& $cli preview --project C:\wyszz\wechat023 --qr-format image --qr-output C:\wyszz\qr-023.png
# 成功标志：打印 TOTAL '770.2 KB' / 788679 字节，并生成 47 KB 左右的二维码图片
```
> 有效期约 **25 分钟**，过期要重出。

### ⑦ 把码传回 NAS 并发给主人

```powershell
$b = [IO.File]::ReadAllBytes("C:\wyszz\qr-023.png")
Invoke-WebRequest -Uri "http://192.168.1.38:8094/" -Method POST -Body $b `
  -Headers @{"X-Filename"="qr-023.png"} -ContentType "application/octet-stream" -TimeoutSec 60
```
NAS 侧落在 `/tmp/vm-upload/qr-023.png`，再拷进 `/vol1/ai/agents/hermes/images/` 才能发出。

### ⑧ 截图取证（可选，用来判断工具状态）

前台化窗口 → 截全屏 → 回传：
```powershell
$wshell.AppActivate($pid) | Out-Null; Start-Sleep 2   # 不前台化会截到别的窗口（坑 10）
```

---

## 3. 坑清单（按踩到时序，每条都带解药）

| # | 坑 | 现象 | 解药 |
|---|---|---|---|
| 1 | `vmctl.py` 参数顺序 | 漏了工具名 → `JSONDecodeError: Expecting value: line 1 column 1` | 必须 `vmctl.py PowerShell @脚本.ps1`，工具名不能省 |
| 2 | 用 `python3 -c` 跑脚本 | 被本机安全闸拦 | 一律写成 `.py`/`.ps1` 文件再跑 |
| 3 | 容器/NAS 端口被旧进程占 | 新服务启动即崩（日志里 `Address already in use`），请求落到旧服务返回 **501 Not Implemented** | 换端口；先 `ss -lntp \| grep <端口>` 看清是谁 |
| 4 | 中文路径 + 提权批处理 | 复制/写入失败、路径乱码 | 提权脚本里用 `%%~fsD` 取短路径 |
| 5 | UAC 弹在 Secure Desktop | `SendInput` 类点击够不着 | 走 QEMU 硬件级按键：`printf 'sendkey alt-y\n' \| nc -U /mnt/ssd/winvm-mcp/mon.sock` |
| 6 | 工具自己关掉了 GL | GPU 进程命令行带 **`--use-gl=disabled`**；模拟器一片空白 | **无法从外部覆盖**（外部传的 `--use-angle=swiftshader` 会被它压掉）；改 `enableGPU` 也没用 |
| 7 | PowerShell 管道吃掉退出码 | `& $cli open ... \| Select-Object -Last 4` 后 `$LASTEXITCODE` 变成假失败；本次误报过一次"打开失败" | 先存变量 `$out = & $cli open ...`，再打印；退出码另取 |
| 8 | 4 GB 内存 | `cli preview` 报 `System.OutOfMemoryException` | 内存提到 6 GB 再跑（本次 6 GB 一次通过） |
| 9 | 截图总是同一张 | 服务器管理器/画图压在最前 | 先 `AppActivate(窗口标题)`，必要时把压住的窗口关掉 |
| 10 | 截图不前台化 | 截到桌面或别的窗口 | 同上；截前 md5 一下确认是**新**图 |
| 11 | 交付包用 `touristappid` | 出码/上传失败 | 改成真实 appid，并同步 MANIFEST 里的 sha256 |
| 12 | 只改配置想开 GL | 改 `WeappLocalData` 里的 `enableGPU` → 无效，且**会被工具写回** | 别改；改了要**还原**（本次改过 `false`，已改回 `true`） |
| 13 | 误判"VM 没有图形能力" | 看到适配器是"基本显示适配器"就下结论 | **先测**：同 VM 内无头 Edge 实测 `WEBGL_OK: WebGL 1.0 (OpenGL ES 2.0 Chromium)` → 这台机器**能**出软件 WebGL，问题在开发者工具自己关 GL |
| 14 | 读屏手段选错 | 拿 OCR 去回答"这画面长什么样" | **分工**：画面/布局 → 自己的视觉；文字/点击坐标 → OCR（`_scripts/ocr-image.py`，输出 `[y= x= p=] 文字`） |
| 15 | NAS 连不进 VM | 想从 NAS 拉 VM 的文件，拉不到 | 一律 VM **主动推**（8094 上传服务）；VM 能连 NAS，NAS 连不进 VM |
| 16 | 日志时区 | VM/工具日志是 `+08:00`，NAS 上 AA 连接器日志是太平洋时间 | 对时间先确认是哪一端的日志 |

---

## 4. 关于"在 VM 里看画面"（结论，别再重走）

```
✗ 小游戏模拟器：起不来。报 [ERROR] routeTo appLaunch timeout，
                并弹窗「无法启动 / 当前设备或微信版本不支持所需的图形能力」
                根因：开发者工具自己带 --use-gl=disabled，外部无法覆盖
✓ 替代方案：跑工程的 Web 版（dist/web/index.html），用本机 chromium 无头渲染 + 截图
           本次实测成功：390×844 与 1920×1080 两种尺寸都出了真画面，
           OCR 读出「声望 / Lv 1 / 每分钟+10.0 / 升级市政厅→ Lv.2 / 花费20金币 / 已保存」
✓ 必须真机的部分：微信 API 那层、真机性能、上传审核
```

---

## 5. 本次交付物与证据

| 项 | 值 |
|---|---|
| G-09 原包 sha256 | `601a6bbc1858db83dbd10dd32b289fa74113494bde6c855d601de18e1744be1b`（与报告一致 ✓） |
| 改造后包 | `/tmp/g09-serve/g09-wechat-023.zip`，194,298 字节，sha256 `86619a77260af3ed4a6cc8296d7d8961cdbcc5345ef7b26dfa2dfa95d2d54529` |
| VM 内工程 | `C:\wyszz\wechat023`（projectname `wyszz-island-0.2.3-pre`，appid `wx1c0ae0869ea1424f`） |
| 预览码 | `C:\wyszz\qr-023.png`（47,260 字节）→ NAS `/vol1/ai/agents/hermes/images/真机预览码-岛主0.2.3-pre-20261019-0036.png` |
| 打包体积 | 0.2.3-pre：`770.2 KB` / 788,679 字节（0.2.1 为 739.6 KB / 757,388） |
| Web 版渲染截图 | `/vol1/ai/agents/hermes/images/游戏Web版渲染-竖屏手机-20261019-001747.png`、`…-桌面宽屏-…png` |

---

## 6. 本次明确**没有**做的事

- ✗ 没改 `game.js` / `game.json` 任何一行（只动了 `project.config.json` 的 appid，这是出码必需）
- ✗ 没动开发者工具安装目录、没有重装/降级
- ✗ 没有替主人点"上传"（只出预览码，不发布）
- ✓ 把先前误改的 `enableGPU` 还原成了 `true`
