# 构建微信小游戏指南

## ✅ 已完成修复

### 修复的问题
1. **导入路径错误** - 所有 TypeScript 脚本的相对导入路径已修正
   - `GameManager.ts` 中的导入从 `'./core/MergeCore'` 改为 `'./MergeCore'`
   - 组件引用从 `'./components/...'` 改为 `'../components/...'`
   - UI 引用从 `'./ui/...'` 改为 `'../ui/...'`
   - 配置引用从 `'./config/...'` 改为 `'../config/GameConfig'`

### 项目结构验证
```
cocos-prototype/
├── .creator/                    ✅ Cocos Creator 项目标识
│   ├── project.json
│   └── default-meta.json
├── assets/
│   ├── audio/                   📁 音频资源目录（待添加）
│   ├── prefabs/
│   │   └── Fruit.prefab        ✅ 水果预制体
│   ├── resources/               📁 动态加载资源目录
│   ├── scenes/
│   │   ── MainGame.scene      ✅ 主游戏场景
│   └── scripts/
│       ├── components/          ✅ 组件脚本（3个）
│       ├── config/              ✅ 配置脚本（1个）
│       ├── core/                ✅ 核心管理器（5个）
│       └── ui/                  ✅ UI脚本（3个）
── package.json                 ✅ npm 依赖配置
├── tsconfig.json                ✅ TypeScript 编译配置
├── build-wechat.ps1             ✅ 微信构建脚本（PowerShell）
├── build-wechat.bat             ✅ 微信构建脚本（Batch）
── wechat-config.js             ✅ 微信性能配置
```

---

## 🚀 在 Cocos Creator 中打开项目

### 步骤 1：启动 Cocos Creator 3.8.x

确保你使用的是 **Cocos Creator 3.8.x** 版本（不是 3.7 或 3.9）。

### 步骤 2：打开项目

1. 点击 **"打开其他项目"**
2. 选择文件夹：**`E:\xxcool\project\gratitude.durian.xpcool.com\cocos-prototype`**
3. 等待导入完成（首次可能需要 2-5 分钟）

### 步骤 3：验证无错误

打开后应该：
- ✅ 没有红色错误提示
- ✅ 资源管理器显示完整的目录结构
- ✅ 可以双击打开 `MainGame.scene`
- ✅ 可以在代码编辑器中看到所有 TypeScript 文件

---

##  搭建完整场景（必须步骤）

当前项目只有最小化的场景结构，需要按照以下步骤搭建完整场景：

### 参考文档
- 📖 [快速入门](README.md) - 5分钟快速运行
- ️ [场景搭建指南](SCENE_SETUP_GUIDE.md) - 详细节点层级和组件配置
- 📘 [完整开发指南](PROJECT_GUIDE.md) - 从零到上架的全流程

### 关键步骤摘要

#### 1. 创建 GameContainer 节点
在 Canvas 下创建：
```
Canvas
└── GameScene
    ├── GameContainer (Node)
    │   ├── LeftWall (Node + BoxCollider2D)
    │   ├── RightWall (Node + BoxCollider2D)
    │   ├── BottomWall (Node + BoxCollider2D)
    │   └── FruitLayer (Node)
    ├── DropArea (Node + UITransform)
    ── GameManagerNode (空节点，挂载 GameManager.ts)
```

#### 2. 绑定 GameManager 属性
选中 `GameManagerNode` → 添加组件 → 搜索 `GameManager` → 拖拽绑定：
- `gameContainer` → GameContainer
- `dropArea` → DropArea
- `fruitPrefab` → Fruit.prefab

#### 3. 测试运行
点击编辑器顶部 **"预览"** 按钮（Ctrl+P），观察水果掉落效果。

---

## 📦 构建微信小游戏包

### 前提条件
- ✅ 已在 Cocos Creator 中成功打开项目
- ✅ 已完成场景搭建并能正常运行
- ✅ 已安装 Cocos Creator 3.8.x

### 方法一：使用 Cocos Creator 编辑器（推荐）

1. **菜单栏**：项目 → 构建发布
2. **平台选择**：WeChat Mini Game
3. **填写配置**：
   - AppID：你的微信小游戏 AppID（测试阶段可用测试号）
   - 构建路径：默认 `build/wechatgame/`
   - 调试模式：勾选（开发阶段）
4. **点击"构建"**
5. **等待完成**（通常需要 1-3 分钟）

### 方法二：使用命令行脚本（高级）

在项目根目录执行：

```powershell
# PowerShell
cd E:\xxcool\project\gratitude.durian.xpcool.com\cocos-prototype
.\build-wechat.ps1 -Version "1.0.0"
```

或

```batch
:: Batch
cd E:\xxcool\project\gratitude.durian.xpcool.com\cocos-prototype
build-wechat.bat 1.0.0
```

⚠️ **注意**：命令行构建需要 Cocos Creator CLI 工具已安装并配置到系统 PATH。

### 构建输出位置

构建完成后，输出目录通常在：
```
E:\xxcool\project\gratitude.durian.xpcool.com\cocos-prototype\build\wechatgame\
```

该目录包含：
- `game.js` - 游戏入口
- `game.json` - 游戏配置
- `project.config.json` - 微信开发者工具配置
- `subpackages/` - 分包目录（如果启用）
- `assets/` - 打包后的资源

---

## 📱 用微信开发者工具测试

### 步骤 1：打开微信开发者工具

1. 启动 **微信开发者工具**
2. 点击 **"导入项目"**
3. 选择构建输出目录：`E:\xxcool\project\gratitude.durian.xpcool.com\cocos-prototype\build\wechatgame\`
4. 填写 AppID（与构建时一致）
5. 点击"导入"

### 步骤 2：真机测试

1. 点击工具栏的 **"预览"** 按钮
2. 用手机微信扫码
3. 在手机上测试游戏功能

### 步骤 3：检查常见问题

- ✅ 广告是否正常显示（需要真实 AppID 和流量主资格）
- ✅ 音效是否正常播放
- ✅ 存档是否正常保存
- ✅ 性能是否流畅（低端机可能卡顿）

---

## ️ 优化建议

### 替换广告位 ID

编辑 `AdManager.ts`，将占位符替换为真实的广告位 ID：

```typescript
// 第 15-16 行
private static readonly REWARD_AD_UNIT_ID = 'adunit-xxxxxxxxxxxxxxxx'; // 替换为你的激励视频广告位 ID
private static readonly INTERSTITIAL_AD_UNIT_ID = 'adunit-yyyyyyyyyyyyyyyy'; // 替换为你的插屏广告位 ID
```

获取广告位 ID：
1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 进入"推广" → "流量主"
3. 创建广告位并复制 ID

### 添加音频资源

将音频文件放入 `assets/audio/` 目录：

```
assets/audio/
── bgm_main.mp3           # 主BGM
├── bgm_golden.mp3         # 金色传说BGM
├── bgm_result.mp3         # 结算BGM
├── sfx_drop_fruit.mp3     # 掉落音效
├── sfx_merge_success.mp3  # 合成音效
└── ...
```

然后在 AudioManager.ts 中配置正确的资源路径。

### 性能优化

编辑 `wechat-config.js`，根据实际测试结果调整：

```javascript
module.exports = {
    performance: {
        targetFPS: 60,           // 目标帧率
        maxFruitsOnScreen: 40,   // 同屏最大水果数（低端机可降至 30）
        gcInterval: 30000,       // GC 触发间隔（毫秒）
    }
};
```

---

## ❓ 常见问题排查

### Q1: 构建时报错 "Module not found"

**原因**：TypeScript 导入路径错误  
**解决**：已修复，重新打开 Cocos Creator 即可

### Q2: 真机测试时广告不显示

**原因**：
- 未开通流量主（需 ≥ 1000 UV）
- 使用的是模拟器而非真机
- 广告位 ID 错误

**解决**：
1. 确保已申请微信流量主资格
2. 使用真机扫码测试
3. 检查 AdManager.ts 中的广告位 ID 是否正确

### Q3: 低端机卡顿严重

**解决**：
1. 降低 `maxFruitsOnScreen` 至 30
2. 减少粒子特效数量
3. 关闭调试日志（发布前）
4. 使用 Texture Packer 合并小图

### Q4: 音频不播放

**原因**：
- 音频文件未正确导入
- 音量设置为 0
- 微信环境限制（需用户交互后才能播放）

**解决**：
1. 确保音频文件在 `assets/audio/` 目录
2. 在 Cocos Creator 中重新导入音频资源
3. 检查 AudioManager.ts 中的初始化逻辑

---

## 📞 技术支持

如遇问题，请查阅：
- 📖 [微信小游戏官方文档](https://developers.weixin.qq.com/minigame/dev/guide/)
- 📖 [Cocos Creator 3.8 手册](https://docs.cocos.com/creator/3.8/manual/zh/)
- 💬 [QoderWork 论坛](https://forum.qoder.com/)

---

**祝你构建顺利！** 🎮🚀