# 《我要当市长》3D 技术预研 · 方案比较报告

> 日期：2026-10-08 ｜ 范围：仅技术预研与独立原型，不修改正式 2D 工程（`/vol1/ai/projects/wyszz-new/app/`）、不修改旧项目 `little-town`、不进入 0.1 第三步
> 结论先行：**推荐 A（Three.js + TypeScript + Vite）**，并已用该方案完成最小旋转原型与浏览器验证。

---

## 一、比较对象与环境约束

| 约束 | 说明 |
| --- | --- |
| 构建环境 | NAS（fnOS / Debian 12）Docker `node:22-bookworm-slim`，**无 GUI / 无 GPU 桌面** |
| 语言 | TypeScript（与 0.1 已定路线 TS + Canvas2D 同语言） |
| 发布目标 | 微信小游戏（Canvas 运行环境） |
| 禁止 | Cocos Creator / Godot / Unity；不装 code-server；不动 NAS 权限网络 |

三个候选方案均在**同一约束**下比较：

- **A. Three.js + TypeScript + Vite**
- **B. 原生 WebGL + TypeScript（自研微型渲染层）**
- **C. LayaAir 3（或其它带微信小游戏官方发布链路的引擎，如 Egret）**

---

## 二、逐项比较

| 比较项 | A. Three.js + TS + Vite | B. 原生 WebGL + TS | C. LayaAir 3 |
| --- | --- | --- | --- |
| 当前 Docker 无头环境构建 | ✅ **本轮实测通过**：`npm install`（23 包 46s）→ `tsc --noEmit` 0 错误 → `vite build` 1.5s，全程无 GUI | ✅ 可构建（无运行时依赖，仅需 tsc/打包器） | ❌/受限：官方工作流依赖 **LayaAirIDE（GUI）** 发布微信小游戏；命令行构建需 IDE 支持，NAS 无桌面。引擎 npm 包形态陈旧（`layaair` npm latest = 1.0.1）。**资料推断：无 GUI 环境不可行；未验证** |
| 透视 / 正交相机 | ✅ `PerspectiveCamera` / `OrthographicCamera` 均内置（原型使用正交相机） | ⚠️ 需自写投影矩阵与视图矩阵 | ✅ 摄像机系统内置（含正交） |
| 拖动旋转 | ✅ 自定义轨道控制 ~100 行；**本轮实测鼠标 10 次 + 触摸 10 次全部生效** | ⚠️ 需自写球面坐标与手势状态机 | ✅ 事件系统内置 |
| 射线点击检测 | ✅ `Raycaster` 开箱即用（含正交相机、遮挡顺序）；**本轮实测 4/4 对象名称命中 + 空白处对照组正确返回 null** | ❌ 需自实现射线-三角形求交、包围盒、场景遮挡 | ✅ 内置 raycast |
| 微信小游戏 Canvas 适配 | ⚠️ 需适配层：three 内部用到 DOM/XHR/Image；社区已有 `three-platformize`（WechatPlatform，宣称小游戏真机+模拟器已适配）、`weapp-adapter`（官方及 finscn 分支）等先例。**资料推断可行，未验证** | ✅ 天然最贴合：只用 `canvas.getContext('webgl')` + `wx.onTouch*`，几乎无需适配层 | ✅ **官方一键发布微信小游戏**（自带 weapp-adapter、分包、开放数据域、引擎插件），链路最成熟 |
| 依赖数量与包体 | 直接依赖 4 个（three / @types/three / typescript / vite），lockfile 24 包；生产构建 JS **537.5 kB（gzip 136.5 kB）**，其中 three 单 chunk 525.8 kB（gzip 131.7 kB） | 0 运行时依赖；包体最小（自研代码量决定） | 引擎库大（MB 级），可走微信「引擎插件」共享缓存降低下载，但主包/插件配置复杂 |
| 学习与维护成本 | 中：three 资料、社区、问答极多；渲染/拾取/阴影由库维护 | **高**：矩阵、着色器、网格、拾取、动画、资源加载全部自研自维护 | 中高：需学 IDE 工作流 + 引擎专有 API + 发布配置；升级受引擎版本绑定 |
| 后续接入建筑升级 | 低：换模型/材质 + 缩放/进度动画即可 | 中高：动画与材质系统自研 | 低：引擎有动画/时间线 |
| 后续接入居民寻访（寻路） | 中：three 之外自写网格 A*，渲染侧只是移动节点 | 高：寻路 + 移动插值 + 头顶文字全自研 | 中：引擎有导航/寻路插件 |
| 后续接入城市装扮 | 低-中：挂点/实例化网格，程序化几何已有先例（本原型 22 网格全程序化） | 高：实例化、批渲染自研 | 低：预制体/资源工作流成熟 |
| 与已定 0.1 架构协同 | ✅ 同一套 tsc + vite + Docker Node 22 工具链；平台适配层概念直接沿用 | ✅ 同左 | ❌ 换栈：引入 IDE 工作流，与 TS+Canvas2D 平台适配层路线冲突 |

---

## 三、明确推荐：A（Three.js + TypeScript + Vite）

理由：

1. **唯一在「无 GUI 的 NAS Docker」里闭环完成的方案**。本轮从 `npm install` → 类型检查 → 生产构建 → 浏览器截图验证全程在 headless 环境完成，未依赖任何编辑器二进制（这是 Cocos/LayaAir 类 IDE 引擎的硬伤）。
2. **相机、射线、光照、阴影都是库能力，不是自研负担**。本原型用正交相机 + Raycaster + 阴影贴图，580 个三角形、22 个网格、46 个 draw call，代码只有 8 个 TS 文件。
3. **微信适配有成熟先例且口子已收好**。原型把「画布创建 / 视口像素比 / 指针输入 / 滚轮 / 名称展示」收敛到 `PlatformAdapter`（`src/platform/types.ts`），微信端只需替换 `platform/browser.ts` 一个文件。
4. **与 0.1 的 TS + Canvas2D 路线同工具链、同分层思想**，未来 2D/3D 之间切换或并存的迁移成本最低。
5. **包体可控**：three gzip 后 131.7 kB，远低于微信小游戏主包 4 MB 限额（留足资源空间）。

### 放弃 B（原生 WebGL）的原因

- 射线检测、场景图、包围盒、材质、阴影、动画、资源加载全部要自研，等于写一个微型引擎；「微信适配更简单」的优势并不成立——适配层（触摸、画布、生命周期）无论哪个方案都要自己写，而渲染侧的自研量 B 远大于 A。
- 后续三个玩法（升级 / 寻访 / 装扮）在 B 下都要从零造轮子，长期维护成本最高。
- 只有当目标包体要求极端苛刻（<100 kB）或需要深度定制渲染管线时才值得选 B，本项目不满足该前提。

### 放弃 C（LayaAir 等 IDE 引擎）的原因

- **硬约束不满足**：发布微信小游戏的工作流绑定 LayaAirIDE（GUI），当前 NAS Docker 无头环境无法构建/发布（与 Cocos 结论同类）；本轮实测 A 方案已能在无头环境跑通全流程。
- 引擎与 IDE 版本绑定，专有 API + 场景/预制体工作流，与已确定的「TS 代码 + 平台适配层」架构冲突。
- 引擎库体积大（MB 级），需要额外依赖微信「引擎插件」机制去摊薄包体，复杂度前置。
- 其优势（官方微信发布链路、开放数据域、分包工具）确实诱人——**若未来出现「必须用官方发布链路才能上架」的硬障碍，可重新评估**，但当前无此证据。

---

## 四、方案 A 的已知代价（不回避）

1. three.js 内部依赖 DOM/XHR/Image，微信端必须上适配层（weapp-adapter / three-platformize 之类），适配层的维护状态是风险点（详见 `02-微信小游戏适配评估.md` 风险清单）。
2. three 升级节奏快（当前 0.186.1），适配层可能滞后 → **锁版本**。
3. WebGL2 / 扩展在微信真机的差异需要真机验证（当前只能标「未验证」）。

---

## 五、结论

| 方案 | 结论 |
| --- | --- |
| A. Three.js + TS + Vite | ✅ **推荐并采用**：无头环境闭环可构建、能力覆盖 3D 原型全部需求、微信适配有先例、与现有工具链协同 |
| B. 原生 WebGL + TS | ❌ 放弃：自研成本与长期维护成本过高，微信适配优势不成立 |
| C. LayaAir 3 等 IDE 引擎 | ❌ 放弃：GUI/IDE 依赖不满足无头构建硬约束，且与既定架构冲突 |
