# 微信小游戏测试与部署指南

## 📋 测试前准备

### 1. 环境检查清单

#### 开发环境
- [ ] Cocos Creator 3.8 已安装
- [ ] 微信开发者工具已安装（最新版本）
- [ ] Node.js 14+ 已安装
- [ ] 项目 AppID: `wxb2b7651c561f9d53`

#### 代码准备
- [ ] 所有 TypeScript 编译通过，无错误
- [ ] 广告位 ID 已替换为真实值
- [ ] 移除或注释掉所有 `console.log`（生产环境）
- [ ] 版本号已更新（package.json / version.json）

#### 资源准备
- [ ] 所有图片已压缩（推荐使用 TinyPNG）
- [ ] 音频文件已优化（MP3 格式，适当比特率）
- [ ] 图标已准备（200x200 PNG，用于微信后台）
- [ ] 截图已准备（5张 1280x720 PNG）

---

## 🧪 本地测试流程

### 步骤1: 构建微信小游戏包

```bash
# 方法1: 使用提供的构建脚本（推荐）
.\build-wechat.ps1 -Version "1.0.0"

# 方法2: 使用 Cocos Creator GUI
# 1. 打开项目
# 2. 菜单栏: 项目 → 构建发布
# 3. 选择平台: WeChat Game
# 4. 点击「构建」
```

### 步骤2: 用微信开发者工具打开

1. 启动微信开发者工具
2. 点击「+」→「导入项目」
3. 选择目录: `build/wechatgame`
4. AppID: `wxb2b7651c561f9d53`
5. 点击「导入」

### 步骤3: 模拟器测试

在微信开发者工具中测试以下内容：

#### 基础功能
- [ ] 游戏能正常启动（3秒内）
- [ ] 主界面显示正常
- [ ] 点击「开始游戏」进入关卡
- [ ] 水果掉落和合成逻辑正常
- [ ] Boss 饱食度系统工作
- [ ] 通关/失败判定正确

#### UI 交互
- [ ] 按钮点击有反馈
- [ ] 面板打开/关闭动画流畅
- [ ] 分数实时更新
- [ ] 道具使用正常

#### 音频系统
- [ ] BGM 正常播放
- [ ] 音效触发正常
- [ ] 音量控制有效
- [ ] 静音功能正常

#### 存档系统
- [ ] 游戏进度自动保存
- [ ] 重新进入游戏能加载存档
- [ ] 最高分记录正确
- [ ] 图鉴解锁状态保持

### 步骤4: 真机测试（必须）

**重要**: 广告在模拟器中无法显示，必须真机测试！

#### 生成预览二维码
1. 微信开发者工具顶部点击「预览」
2. 等待构建完成
3. 扫描二维码

#### 真机测试清单

##### iOS 设备（iPhone 8 或以上）
- [ ] 游戏启动时间 < 3秒
- [ ] 帧率稳定 60 FPS
- [ ] 内存占用 < 200 MB
- [ ] 触摸响应灵敏
- [ ] 音频播放正常
- [ ] 广告能正常展示（激励视频 + 插屏）

##### Android 设备（中高端机型）
- [ ] 游戏启动时间 < 3秒
- [ ] 帧率稳定 60 FPS
- [ ] 内存占用 < 300 MB
- [ ] 触摸响应灵敏
- [ ] 音频播放正常
- [ ] 广告能正常展示

##### 低端机测试（可选但推荐）
- [ ] 降级到 30 FPS 后流畅运行
- [ ] 减少水果数量后不卡顿
- [ ] 内存占用可控（不崩溃）

---

## 🐛 常见问题排查

### 问题1: 游戏启动黑屏

**可能原因**:
- 资源路径错误
- TypeScript 编译失败
- 微信环境兼容性问题

**排查步骤**:
```javascript
// 1. 在 game.js 添加日志
console.log('[Game] 开始加载...');

// 2. 在 main.js 添加日志
class Main {
    constructor() {
        console.log('[Main] 构造函数调用');
        this.initWXEnvironment();
        console.log('[Main] 微信环境初始化完成');
    }
}
```

**解决方案**:
- 检查 `project.config.json` 中的 `appid` 是否正确
- 确认所有资源文件在 `res` 目录下
- 查看控制台错误信息

### 问题2: 广告不显示

**可能原因**:
- 广告位 ID 未替换
- 模拟器测试（广告只在真机显示）
- 网络问题
- 广告未预加载

**排查步骤**:
```typescript
// AdManager.ts 中添加详细日志
static showReviveAd(onReward?: () => void, onClose?: () => void): void {
    console.log('[AdManager] 尝试展示复活广告');
    console.log('[AdManager] 广告实例:', this._reviveAd);
    
    if (!this._reviveAd) {
        console.error('[AdManager] 广告实例为空，可能未初始化');
        return;
    }
    
    // ... 其余代码
}
```

**解决方案**:
1. 确认已替换广告位 ID:
```typescript
// AdManager.ts
private static readonly AD_UNIT_ID_REVIVE = 'adunit-xxxxxxxxxxxx'; // 替换为真实ID
```

2. 真机测试（不要依赖模拟器）

3. 检查网络连接（WiFi/4G）

4. 提前预加载广告:
```typescript
// 在游戏启动3秒后预加载
setTimeout(() => {
    AdManager.preloadAds();
}, 3000);
```

### 问题3: 内存泄漏

**症状**:
- 长时间游戏后卡顿
- 切换场景后内存不下降
- 最终导致崩溃

**排查工具**:
```typescript
// 添加内存监控
class MemoryMonitor {
    static start() {
        setInterval(() => {
            if (wx.getSystemInfoSync) {
                const info = wx.getSystemInfoSync();
                const memoryMB = info.memoryUsage / 1024 / 1024;
                console.log(`[Memory] 当前内存: ${memoryMB.toFixed(1)} MB`);
                
                if (memoryMB > 180) {
                    console.warn('[Memory] ⚠️ 内存警告！');
                }
            }
        }, 10000);
    }
}
```

**解决方案**:
```typescript
// 1. 场景切换时清理资源
onDestroy() {
    // 停止所有定时器
    this.unscheduleAllCallbacks();
    
    // 移除所有子节点
    this.node.removeAllChildren();
    
    // 释放资源
    resources.releaseAll();
    
    // 触发 GC
    if (wx.triggerGC) {
        setTimeout(() => wx.triggerGC(), 500);
    }
}

// 2. 对象池管理
class ObjectPool {
    clear() {
        this.pool.forEach(obj => {
            if (obj.destroy) {
                obj.destroy();
            }
        });
        this.pool = [];
    }
}
```

### 问题4: 音频中断后不恢复

**症状**:
- 来电后 BGM 不继续播放
- 切换到其他应用再返回，无声

**解决方案**:
已在 `AudioManager.ts` 中实现，确保以下代码存在:

```typescript
private _initWeChatAudio(): void {
    // 监听音频中断开始
    if (wx.onAudioInterruptionBegin) {
        wx.onAudioInterruptionBegin(() => {
            this._onAudioInterruptBegin();
        });
    }

    // 监听音频中断结束
    if (wx.onAudioInterruptionEnd) {
        wx.onAudioInterruptionEnd(() => {
            this._onAudioInterruptEnd();
        });
    }
}

private _onAudioInterruptEnd(): void {
    // 恢复 BGM
    if (this._bgmWasPlaying && !this._muted) {
        this._bgmSource?.resume();
    }
}
```

---

## 📤 上传到微信后台

### 步骤1: 准备提审材料

#### 游戏截图（5张）
要求：
- 尺寸：1280x720 或更高
- 格式：PNG 或 JPG
- 内容：真实 gameplay 截图，包含：
  1. 主界面
  2. 游戏进行中
  3. 金色传说特效
  4. Boss 投喂界面
  5. 结算面板

#### 游戏简介
```
《报恩榴莲》是一款创新的三三合成益智小游戏。

玩法特色：
🎮 三个相同水果碰在一起自动合成更高级水果
🍉 9级水果链，终极形态是拟人化报恩榴莲
👾 20个可爱 Boss，投喂它们通关
✨ 合成终极水果触发「金色传说」史诗特效
💎 收集图鉴，解锁所有水果形态

轻松休闲，适合碎片时间游玩~
```

#### 分类选择
- 一级分类：游戏
- 二级分类：休闲 → 益智

### 步骤2: 上传版本

#### 方法1: 微信开发者工具上传
1. 点击顶部「上传」按钮
2. 填写版本号：`1.0.0`
3. 填写版本备注：
```
v1.0.0 首次提交
- 核心三三合成玩法
- 20个关卡
- 广告系统接入
- 存档系统
```
4. 点击「上传」
5. 等待上传完成（约1-5分钟）

#### 方法2: 命令行上传（自动化）
```bash
# 需要安装 miniprogram-ci
npm install -g miniprogram-ci

# 上传
miniprogram-ci upload \
  --pp ./build/wechatgame \
  --pkp private.key \
  --appid wxb2b7651c561f9d53 \
  --version 1.0.0 \
  --desc "v1.0.0 首次提交"
```

### 步骤3: 提交审核

1. 登录 [微信公众平台](https://mp.weixin.qq.com/)
2. 左侧菜单：管理 → 版本管理
3. 找到刚上传的版本，点击「提交审核」
4. 填写审核信息：
   - **功能页面**：列出所有可访问的页面路径
   - **测试账号**：无需提供（单机游戏）
   - **补充说明**：
   ```
   纯单机益智游戏，无需特殊权限。
   广告位已配置，可在真机测试中查看。
   ```
5. 上传截图（5张）
6. 确认分类正确
7. 点击「提交」

### 审核时间
- **通常**：1-3个工作日
- **加急**：联系客服（需理由）

---

## ✅ 审核通过后的操作

### 步骤1: 发布版本

1. 收到审核通过通知
2. 登录微信公众平台
3. 版本管理 → 找到通过的版本
4. 点击「全量发布」

### 步骤2: 灰度发布（推荐）

首次发布建议先灰度测试：
1. 点击「灰度发布」
2. 设置比例：10%
3. 观察数据 24-48 小时
4. 无问题后全量发布

### 步骤3: 数据监控

发布后关注以下指标：

#### 关键指标（微信公众平台查看）
- **新增用户**：日新增、周新增
- **活跃用户**：DAU、WAU
- **留存率**：次日留存、7日留存
- **使用时长**：平均单次时长
- **广告收入**：eCPM、总收入

#### 性能指标（通过 wx.reportAnalytics 上报）
```typescript
// 示例：上报性能数据
wx.reportAnalytics('perf_data', {
    fps: 60,
    memory_mb: 150,
    level: 5,
    play_time_sec: 300
});
```

---

## 🔧 运营与维护

### 日常维护

#### 每周任务
- [ ] 查看用户反馈（公众号留言、客服消息）
- [ ] 分析留存率数据
- [ ] 监控广告 eCPM
- [ ] 检查崩溃率（目标 < 1%）

#### 每月任务
- [ ] 规划新版本内容
- [ ] A/B 测试广告频控
- [ ] 优化低留存关卡
- [ ] 更新排行榜数据

### 版本迭代策略

#### v1.1.0 建议内容
- 新增 10 个关卡（21-30）
- 新增 3 种道具
- 优化新手引导
- 修复已知 bug

#### v1.2.0 建议内容
- 每日挑战模式
- 好友排行榜
- 成就系统
- 季节性活动

### 用户获取

#### 免费渠道
1. **微信搜索优化**
   - 游戏名称包含关键词：「合成」「榴莲」「休闲」
   - 简介优化 SEO

2. **社交分享**
   - 设计分享诱因：「我合成了报恩榴莲，你也来试试！」
   - 分享奖励：金币或道具

3. **微信群传播**
   - 制作有趣的游戏片段 GIF
   - 在相关群分享

#### 付费渠道（后期）
1. 微信朋友圈广告
2. 小程序互推
3. KOL 合作

---

## 📊 数据分析模板

### 关键事件埋点

```typescript
// 游戏启动
wx.reportAnalytics('game_start', {
    level: currentLevel,
    timestamp: Date.now()
});

// 关卡完成
wx.reportAnalytics('level_complete', {
    level: levelNumber,
    score: finalScore,
    time_used: gameTime,
    continues_used: continueCount
});

// 广告展示
wx.reportAnalytics('ad_shown', {
    ad_type: 'rewarded_video',
    placement: 'game_over'
});

// 广告完成
wx.reportAnalytics('ad_completed', {
    ad_type: 'rewarded_video',
    reward_given: true
});

// 道具使用
wx.reportAnalytics('item_used', {
    item_id: itemId,
    level: currentLevel
});
```

### 数据看板建议

| 指标 | 目标值 | 监控频率 |
|------|--------|----------|
| 次日留存 | > 30% | 每日 |
| 7日留存 | > 10% | 每周 |
| 平均时长 | > 5分钟 | 每日 |
| 广告完成率 | > 60% | 每日 |
| eCPM | > ¥50 | 每周 |
| 崩溃率 | < 1% | 每日 |

---

## 🎯 总结

### 上线前最后检查

- [ ] 所有功能在真机测试通过
- [ ] 广告能正常展示和完成
- [ ] 存档系统稳定
- [ ] 包体大小符合规范（主包 ≤ 20MB）
- [ ] 启动时间 < 3秒
- [ ] 帧率稳定 60 FPS
- [ ] 内存占用合理
- [ ] 提审材料准备齐全

### 成功要素

1. **核心玩法**：三三合成差异化，有记忆点
2. **情感连接**：报恩榴莲 IP，建立共鸣
3. **传播性**：金色传说名场面，适合短视频
4. **商业化**：广告频控合理，不影响体验
5. **持续运营**：数据驱动迭代，快速试错

---

**祝《报恩榴莲》上线顺利，大获成功！** 🎉🍈✨