# 微信适配风险清单 与 后续正式开发建议

> 日期：2026-10-08 ｜ 配套文档：`01-技术方案比较报告.md`、`02-微信小游戏适配评估.md`、`03-验证结果与性能记录.md`

---

## 一、微信小游戏适配风险清单

| # | 风险 | 等级 | 说明与缓解 |
| --- | --- | --- | --- |
| 1 | three.js 内部依赖 DOM / XHR / Image | 中 | 需 `weapp-adapter` 或 `three-platformize` 补齐；**缓解**：适配层代码进仓库锁定版本，不追新 |
| 2 | 适配层维护状态（`three-platformize` CHANGELOG 停更于 2021） | 中高 | 与 three 0.186.1 的兼容性未知；**缓解**：评估期先跑通 weapp-adapter 路线；不行则降 three 版本或自补最小适配面（本原型只需 canvas/Image/XHR 三个口子） |
| 3 | WebGL2 / 纹理扩展在微信真机可用性 | 中 | 阴影贴图依赖 framebuffer/深度纹理；**缓解**：预留「假阴影」降级开关（圆形贴片），低端机关闭 shadowMap |
| 4 | iOS 微信内存（社区反馈 three 在 iOS 小程序多次切页崩溃） | 中高 | **缓解**：严格 dispose 几何体/材质；场景常驻单页；避免多次重建渲染器 |
| 5 | 包体：three gzip 131.7 kB + 适配层 + 未来资源 | 低 | 主包 4 MB 限额内目前充裕；**缓解**：模型/贴图走分包或远程（需备案域名） |
| 6 | 触摸语义差异（`touchcancel`、多点顺序、双指手势） | 中 | **缓解**：`SpikePointerEvent` 已做归一化；真机调阈值（当前拖动阈值 8 px） |
| 7 | `requestAnimationFrame` / `performance` / 生命周期差异 | 低 | **缓解**：`wx.onShow/onHide` 暂停渲染；时间源统一走适配层 |
| 8 | 不能用 ES module / `<script type="module">` | 低 | **缓解**：vite 打包产物本来就是 bundle；微信入口 `game.js` 引入即可 |
| 9 | 微信开发者工具与真机 GLSL 编译差异 | 低-中 | **缓解**：着色器只用 three 内置材质（不写自定义 shader），降低差异面 |
| 10 | 无 DOM 后的 UI（名称条/提示条） | 低 | **缓解**：改 canvas 2D 文字或 `wx.showToast`，接口已在 `PlatformAdapter.showObjectName` 收敛 |

**总体判断**：适配风险**集中在 1、2、4 三条**（适配层与 iOS 内存），均为工程可管理问题，不构成路线否定；但在微信开发者工具 + 真机跑通之前，**不能宣称「微信小游戏可行已验证」**。

---

## 二、后续正式开发建议

### 1. 架构（可直接沿用本原型的三条经验）

- **平台适配层**：`PlatformAdapter`（画布/视口/像素比/输入/缩放/文字展示）保持一个接口多实现（`browser.ts` / 未来 `wechat.ts`），3D 场景代码零改动进微信。
- **程序化几何优先**：本原型 22 个网格 0 贴图 0 外部模型，包体与加载风险最小；建筑升级只需换「网格 + 配色」函数。
- **调试接口常态化**：`window.__spike` 式只读统计（计数/FPS/三角形/投影坐标）让自动化验证（CDP 脚本）可复用到后续每一步。

### 2. 下一步（建议顺序，均属「进入正式开发后」，本轮不做）

1. **微信适配验证**：在有微信开发者工具的机器（Windows/macOS）上建最小 `game.js` 工程，把 `wechat.ts` 适配层写出来，先跑「清屏 + 一个三角形」，再跑本原型场景。产出「已验证/仍推断」清单更新。
2. **真机触摸与性能基线**：低端安卓机 + iPhone 各一台，记录 FPS、内存、启动耗时。
3. **假阴影开关**：为低端机准备 blob shadow 降级路径。
4. **玩法接入预留**：建筑升级 = 模型/材质注册表 + 缩放动画；居民寻访 = 网格 A*（岛顶栅格化）；城市装扮 = 挂点系统（`userData.slot`）。三者都只动 `world/` 与新增 `sim/`，不动 `platform/`。

### 3. 风险前置动作

- 锁定 `three@0.186.1`，升级前在分支验证适配层兼容。
- 适配层选型尽早定（weapp-adapter vs three-platformize），避免后期切换成本。
- iOS 内存：在场景切换/重建路径上加 dispose 计数验证。

### 4. 边界声明

- 本原型**不含**金币、声望、升级、存档、广告、后端、微信 AppID，任何页面都不依赖正式游戏数值逻辑。
- 本轮**未进入 0.1 第三步**，未修改 `/vol1/ai/projects/wyszz-new/app/` 与 `/vol1/ai/projects/little-town` 的任何文件。
