# 《报恩榴莲》微信小程序 - 测试与部署指南

> 🎮 纯原生微信小程序版本，无需 Cocos Creator

---

## 🚀 快速开始（5分钟运行）

### 前置要求

- ✅ 微信开发者工具已安装（[下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)）
- ✅ 拥有微信小程序 AppID（或使用测试号）

### 步骤 1：导入项目

1. 打开 **微信开发者工具**
2. 点击 **"导入项目"** 或 **"+"** 按钮
3. 选择目录：`E:\xxcool\project\gratitude.durian.xpcool.com\wechat-miniprogram`
4. 填写 AppID（如果没有，可先使用测试号）
5. 点击 **"导入"**

### 步骤 2：配置 AppID（如果需要）

如果使用的是自己的 AppID，需要修改以下文件：

**app.json** 和 **project.config.json** 中的 `appid` 字段：
```json
{
  "appid": "你的AppID"
}
```

### 步骤 3：编译并预览

1. 等待项目编译完成（通常几秒）
2. 左侧模拟器会自动显示游戏界面
3. 点击顶部区域掉落水果，观察物理效果和合成逻辑

**✅ 如果看到水果掉落并能合成，核心玩法已跑通！**

---

## 📱 真机测试

### 方法 1：扫码预览

1. 在微信开发者工具中点击 **"预览"** 按钮
2. 用微信扫描生成的二维码
3. 在手机上体验游戏

### 方法 2：真机调试

1. 点击 **"真机调试"** 按钮
2. 扫码连接真机
3. 可以实时查看控制台日志和性能数据

---

## 🎯 功能测试清单

### ✅ 核心玩法

- [ ] 点击屏幕顶部能掉落水果
- [ ] 水果受重力影响下落
- [ ] 水果与地面、墙壁碰撞正常
- [ ] 相同等级的两个水果接触时自动合成
- [ ] 合成后生成更高等级的水果
- [ ] 分数随合成增加
- [ ] 连击系统正常工作（2秒内连续合成）

### ✅ Boss 系统

- [ ] Boss 进度条显示正确
- [ ] 投喂达到目标等级的水果时进度增加
- [ ] 进度满时触发通关

### ✅ UI 交互

- [ ] 分数、连击数实时更新
- [ ] 下一个水果预览显示正确
- [ ] 暂停/继续按钮工作正常
- [ ] 道具按钮（炸弹、冰冻）可用
- [ ] 结算面板在通关/失败时显示

### ✅ 音频系统

- [ ] 游戏开始时播放背景音乐
- [ ] 暂停时停止BGM，继续时恢复
- [ ] 掉落水果时播放音效
- [ ] 合成时播放音效
- [ ] 通关/失败时播放对应音效
- [ ] 金色传说特效播放特殊音效

> **注意**：音频文件需要手动添加到 `audio/` 目录，详见下方"音频资源配置"章节

### ✅ 广告系统（需配置真实广告位ID）

- [ ] 复活按钮点击后弹出激励视频
- [ ] 观看完整广告后成功复活
- [ ] 插屏广告在关卡切换时显示

> **注意**：广告功能需要开通流量主并配置真实广告位ID

### ✅ 存档系统

- [ ] 游戏进度自动保存
- [ ] 重新进入小游戏时加载上次进度
- [ ] 最高分数、连击记录正确

---

## 🎨 美术资源替换

当前版本使用彩色圆形代表水果，如需替换为精美贴图：

### 水果精灵图规格

| 等级 | 名称 | 推荐尺寸 | 文件名建议 |
|------|------|----------|-----------|
| 1 | 果切丁 | 36x36 | fruit_1.png |
| 2 | 西瓜片 | 50x50 | fruit_2.png |
| 3 | 紫葡萄 | 64x64 | fruit_3.png |
| 4 | 黄柠檬 | 80x80 | fruit_4.png |
| 5 | 红苹果 | 96x96 | fruit_5.png |
| 6 | 甜橙 | 112x112 | fruit_6.png |
| 7 | 粉桃子 | 128x128 | fruit_7.png |
| 8 | 金菠萝 | 152x152 | fruit_8.png |
| 9 | 报恩榴莲 | 180x180 | fruit_9.png |

### 替换步骤

1. 准备9张PNG图片（透明背景）
2. 放入 `assets/images/` 目录
3. 修改 `pages/game/index.js` 的渲染逻辑，将圆形绘制改为图片绘制：

```javascript
// 原代码（绘制圆形）
ctx.beginPath();
ctx.arc(fruit.x, fruit.y, fruit.radius, 0, 2 * Math.PI);
ctx.fillStyle = fruit.color;
ctx.fill();

// 替换为（绘制图片）
const imgPath = `/assets/images/fruit_${fruit.level}.png`;
ctx.drawImage(imgPath, fruit.x - fruit.radius, fruit.y - fruit.radius, 
              fruit.radius * 2, fruit.radius * 2);
```

---

## 🔊 音频资源配置

### 必需音频文件

#### BGM（背景音乐）
- `bgm_main.mp3` - 主游戏BGM（循环播放）
- `bgm_golden.mp3` - 金色传说BGM（可选）
- `bgm_result.mp3` - 结算界面BGM（可选）

#### SFX（音效）
- `sfx_drop.mp3` - 水果掉落
- `sfx_merge.mp3` - 合成成功
- `sfx_combo2.mp3` - 2连击
- `sfx_combo3.mp3` - 3连击
- `sfx_combo4.mp3` - 4连击
- `sfx_combo5.mp3` - 5连击
- `sfx_golden.mp3` - 金色传说
- `sfx_clear.mp3` - 通关
- `sfx_gameover.mp3` - 失败
- `sfx_revive.mp3` - 复活

### 存放路径

将所有音频文件放入 `audio/` 目录：
```
wechat-miniprogram/
└── audio/
    ├── bgm_main.mp3
    ├── sfx_drop.mp3
    ├── sfx_merge.mp3
    └── ...（其他音效）
```

### AI 音频生成提示词

可使用以下工具生成音频：
- **Suno AI** / **Udio** - 生成BGM
- **ElevenLabs** - 生成语音
- **Freesound.org** - 免费音效素材

详细提示词请参考项目根目录的 `03_报恩榴莲_音效与台词语料设计.md`

---

## ⚙️ 关键参数调优

所有游戏参数都在 `pages/game/index.js` 中：

### 物理参数

```javascript
updateFruits(dt) {
  const gravity = 0.5;      // 重力加速度（增大则下落更快）
  const damping = 0.98;     // 阻尼系数（减小则摩擦更大）
  const bounce = 0.3;       // 弹性系数（增大则弹跳更高）
  const groundY = 600;      // 地面Y坐标
  // ...
}
```

**调优建议**：
- 如果觉得水果下落太慢，增加 `gravity`（如 0.8）
- 如果觉得水果弹跳太多，减小 `bounce`（如 0.2）
- 如果想让水果更快静止，减小 `damping`（如 0.95）

### 关卡配置

```javascript
const LEVEL_CONFIGS = [
  { level: 1, bossName: '贪吃喵星人', targetLevel: 3, feedCount: 3, dropMin: 1, dropMax: 2 },
  { level: 2, bossName: '吃货柴犬', targetLevel: 4, feedCount: 4, dropMin: 1, dropMax: 3 },
  { level: 3, bossName: '美食家熊猫', targetLevel: 5, feedCount: 5, dropMin: 2, dropMax: 4 },
  // 可继续添加更多关卡...
];
```

**参数说明**：
- `targetLevel`: Boss需要的水果等级（玩家需合成到此等级才能投喂）
- `feedCount`: 需要投喂的次数
- `dropMin/dropMax`: 掉落水果的等级范围

**难度调整**：
- 想降低难度：减小 `targetLevel` 和 `feedCount`
- 想提高难度：增大 `targetLevel` 和 `feedCount`

### 失败判定

```javascript
checkFailCondition(dt) {
  const warningY = 150;  // 警戒线Y坐标（越小越难）
  // 超过3秒则失败
  if (this.gameState.failTimer >= 3000) {
    this.handleGameOver();
  }
}
```

**调优建议**：
- 想降低难度：增大 `warningY`（如 200）或增加超时时间（如 5000）
- 想提高难度：减小 `warningY`（如 100）或减少超时时间（如 2000）

---

## 📱 微信小游戏上架

### 步骤 1：开通流量主（可选，用于广告变现）

1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 进入小程序后台 → 推广 → 流量主
3. 满足条件（累计独立访客 ≥ 1000）后申请开通
4. 创建广告位，获取广告位ID

### 步骤 2：配置广告位ID

修改 `app.js` 中的广告位ID：

```javascript
// 激励视频广告（复活用）
this.rewardedVideoAd = wx.createRewardedVideoAd({
  adUnitId: '你的激励视频广告位ID'  // 替换这里
});

// 插屏广告
this.interstitialAd = wx.createInterstitialAd({
  adUnitId: '你的插屏广告位ID'  // 替换这里
});
```

### 步骤 3：上传代码

1. 在微信开发者工具中点击 **"上传"**
2. 填写版本号和备注
3. 等待上传完成

### 步骤 4：提交审核

1. 登录微信公众平台
2. 进入小程序后台 → 版本管理
3. 找到刚上传的版本，点击 **"提交审核"**
4. 填写审核信息（游戏分类、服务类目等）
5. 等待审核通过（通常1-3个工作日）

### 步骤 5：发布上线

审核通过后，在后台点击 **"发布"** 即可上线。

---

## 🐛 常见问题排查

### Q1: 水果不掉下来？

**检查清单**：
- [ ] Canvas 上下文是否正确初始化（`wx.createCanvasContext`）
- [ ] `onTouchStart` 事件是否绑定到 canvas
- [ ] `updateFruits` 函数是否在每帧调用

### Q2: 合成判定不触发？

**检查清单**：
- [ ] `checkMerges()` 是否在每帧调用
- [ ] 距离判断阈值是否合理（当前为 `radius1 + radius2 - 5`）
- [ ] 水果的 `level` 属性是否正确设置

### Q3: 音频不播放？

**可能原因**：
- 音频文件不存在于 `audio/` 目录
- 文件路径错误（注意大小写）
- 微信开发者工具中禁用了音频（检查设置）
- 真机上需要用户交互后才能播放音频（这是微信的限制）

**解决方法**：
- 确认音频文件存在且格式正确（MP3）
- 检查 `AudioManager.js` 中的路径映射
- 在真机上测试（模拟器音频支持有限）

### Q4: 广告不显示？

**可能原因**：
- 未开通流量主
- 广告位ID错误或未配置
- 使用的是模拟器而非真机（部分广告类型不支持模拟器）
- 广告加载失败（网络问题或广告库存不足）

**解决方法**：
- 确认已开通流量主并配置正确的广告位ID
- 在真机上测试
- 查看控制台是否有广告加载失败的错误信息

### Q5: 存档不生效？

**检查清单**：
- [ ] `app.saveGameData()` 是否在适当时机调用
- [ ] `wx.setStorageSync` 是否执行成功
- [ ] 重新进入时是否调用 `app.loadGameData()`

---

## 📊 性能优化建议

### 1. 限制同屏水果数量

```javascript
// 在 dropFruit 前检查
if (this.gameState.fruits.length >= 50) {
  wx.showToast({ title: '水果太多了', icon: 'none' });
  return;
}
```

### 2. 对象池优化（高级）

对于频繁创建/销毁的水果，可以使用对象池复用节点，减少GC压力。

### 3. 降低渲染频率

如果不需要60fps，可以降低渲染频率：

```javascript
startGameLoop() {
  const loop = () => {
    if (!this.data.isPaused) {
      this.update();
      this.render();
    }
    
    // 降低到30fps
    setTimeout(() => requestAnimationFrame(loop), 33);
  };
  
  loop();
}
```

### 4. 使用 Canvas 离屏渲染

对于复杂的特效，可以先渲染到离屏Canvas，再绘制到主Canvas。

---

## 📞 技术支持

### 官方文档
- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [Canvas API 参考](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.createCanvasContext.html)
- [音频API参考](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html)

### 社区支持
- [微信开放社区](https://developers.weixin.qq.com/community/)
- [QoderWork 论坛](https://forum.qoder.com/)

---

## 🎉 下一步行动

1. **立即测试**：按照"快速开始"导入项目并运行
2. **替换美术资源**：准备9个水果精灵图和Boss图片
3. **配置音频**：生成或下载音频文件放入 `audio/` 目录
4. **真机测试**：扫码在手机上体验
5. **配置广告**（可选）：开通流量主并配置广告位ID
6. **提交审核**：上传代码并提交微信审核

**祝你上架顺利！🚀**

---

**项目版本**：v1.0  
**最后更新**：2026-08-14  
**适用平台**：微信小程序  
**许可证**：MIT