gratitude.durian.xpcool.com/wechat-miniprogram/TESTING_GUIDE.md

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

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

---

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

前置要求

• ✅ 微信开发者工具已安装（下载地址）
• ✅ 拥有微信小程序 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 字段：

{
  "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 的渲染逻辑，将圆形绘制改为图片绘制：

// 原代码（绘制圆形）
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 中：

物理参数

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）

关卡配置

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

失败判定

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

调优建议：

• 想降低难度：增大 warningY（如 200）或增加超时时间（如 5000）
• 想提高难度：减小 warningY（如 100）或减少超时时间（如 2000）

---

📱 微信小游戏上架

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

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

步骤 2：配置广告位ID

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

// 激励视频广告（复活用）
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. 限制同屏水果数量

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

2. 对象池优化（高级）

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

3. 降低渲染频率

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

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

4. 使用 Canvas 离屏渲染

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

---

📞 技术支持

官方文档

• 微信小程序开发文档
• Canvas API 参考
• 音频API参考

社区支持

• 微信开放社区
• QoderWork 论坛

---

🎉 下一步行动

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

祝你上架顺利！🚀

---

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