gratitude.durian.xpcool.com/WECHAT_QUICK_REFERENCE.md

# 微信小游戏开发速查卡

## 🚀 快速开始

### 构建命令
```bash
# PowerShell（Windows）
.\build-wechat.ps1 -Version "1.0.0"

# Batch（Windows）
build-wechat.bat

# Cocos Creator CLI
cocos build --platform wechatgame --output ./build/wechatgame
```

### 真机测试
1. 微信开发者工具 → 点击「预览」
2. 扫描二维码
3. 在手机上测试功能

---

## 📦 包体限制

| 项目 | 限制 | 检查命令 |
|------|------|----------|
| 主包大小 | ≤ 20 MB | `ls -lh build/wechatgame` |
| 总包大小 | ≤ 200 MB | 同上 |
| 代码文件大小 | ≤ 8 MB | 检查 `game.js` |
| 单次加载资源 | ≤ 10 MB | 监控内存 |

---

## 🔑 常用微信 API

### 系统信息
```typescript
const info = wx.getSystemInfoSync();
console.log(info.model);      // 设备型号
console.log(info.system);     // 操作系统版本
console.log(info.platform);   // 平台
console.log(info.memoryUsage); // 内存使用
```

### 数据存储
```typescript
// 同步存储
wx.setStorageSync('key', 'value');
const value = wx.getStorageSync('key');
wx.removeStorageSync('key');

// 异步存储
wx.setStorage({
    key: 'key',
    data: 'value',
    success: () => console.log('保存成功')
});
```

### 广告 API
```typescript
// 激励视频广告
const rewardedAd = wx.createRewardedVideoAd({
    adUnitId: 'adunit-xxxxxxxx'
});

rewardedAd.onClose((res) => {
    if (res.isEnded) {
        // 观看完成，发放奖励
    }
});

rewardedAd.show().catch(() => {
    rewardedAd.load().then(() => rewardedAd.show());
});

// 插屏广告
const interstitialAd = wx.createInterstitialAd({
    adUnitId: 'adunit-xxxxxxxx'
});

interstitialAd.show();
```

### 音频控制
```typescript
// 监听音频中断
wx.onAudioInterruptionBegin(() => {
    // 来电、通知等，暂停音频
});

wx.onAudioInterruptionEnd(() => {
    // 中断结束，恢复音频
});
```

### 性能优化
```typescript
// 设置目标帧率
wx.setPreferredFramesPerSecond(60);

// 主动触发 GC
wx.triggerGC();

// 数据上报
wx.reportAnalytics('event_name', {
    key1: 'value1',
    key2: 'value2'
});
```

---

## 🎨 资源规范

### 图片
| 类型 | 格式 | 尺寸 | 压缩 |
|------|------|------|------|
| UI 图标 | PNG | 按需 | TinyPNG |
| 背景图 | JPG/WebP | 1920x1080 | 质量 80% |
| 水果贴图 | PNG | 256x256 | TinyPNG |
| 特效 | PNG 序列帧 | 128x128 | 减少帧数 |

### 音频
| 类型 | 格式 | 比特率 | 声道 |
|------|------|--------|------|
| BGM | MP3 | 128kbps | 立体声 |
| SFX | MP3 | 96kbps | 单声道 |
| Voice | MP3 | 64kbps | 单声道 |

---

## 🐛 调试技巧

### 控制台日志
```typescript
// 开发环境输出
console.log('[Debug] 消息');
console.warn('[Warning] 警告');
console.error('[Error] 错误');

// 生产环境禁用
if (!DEBUG_MODE) {
    console.log = () => {};
}
```

### 性能监控
```typescript
// FPS 监控
const fps = director.getScheduler().getFramesPerSecond();

// 内存监控
if (wx.getSystemInfoSync) {
    const mem = wx.getSystemInfoSync().memoryUsage;
    console.log(`内存: ${(mem / 1024 / 1024).toFixed(1)} MB`);
}

// Draw Calls
const drawCalls = director.root?.batcher?.queue?.length;
```

### 真机调试
1. 微信开发者工具 → 「调试」→ 「打开调试」
2. 手机会显示 vConsole 面板
3. 查看日志、网络请求、性能数据

---

## ⚡ 性能优化速查

### 代码优化
```typescript
// ✅ 使用对象池
const pool: Fruit[] = [];
function getFruit() {
    return pool.pop() || new Fruit();
}

// ❌ 避免频繁创建
function badExample() {
    const obj = { x: 1, y: 2 }; // 每帧创建
}
```

### 渲染优化
```typescript
// ✅ 合并相同材质的 Sprite
batchNode.addChild(fruit1);
batchNode.addChild(fruit2);

// ✅ 隐藏不可见对象
node.active = false;  // 而不是 opacity = 0

// ❌ 避免动态修改材质
```

### 内存管理
```typescript
// 场景切换时清理
onDestroy() {
    this.unscheduleAllCallbacks();
    this.node.removeAllChildren();
    resources.releaseAll();
    if (wx.triggerGC) wx.triggerGC();
}
```

---

## 📊 关键指标

### 性能指标
| 指标 | 目标值 | 警戒值 |
|------|--------|--------|
| FPS | 60 | < 45 |
| 启动时间 | < 3s | > 5s |
| 内存占用 | < 200MB | > 250MB |
| Draw Calls | < 100 | > 200 |
| 崩溃率 | < 1% | > 3% |

### 业务指标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 次日留存 | > 30% | 新用户第二天回来 |
| 7日留存 | > 10% | 新用户第七天回来 |
| 平均时长 | > 5min | 单次游戏时长 |
| 广告完成率 | > 60% | 激励视频看完率 |
| eCPM | > ¥50 | 千次展示收入 |

---

## 🔧 常见问题

### Q: 广告不显示？
- 必须真机测试（模拟器不显示）
- 检查广告位 ID 是否正确
- 确认网络连接正常
- 检查网络权限

### Q: 启动慢？
- 使用分包加载
- 延迟加载非核心资源
- 压缩图片和音频
- 减少首屏渲染元素

### Q: 内存泄漏？
- 检查定时器是否清除
- 确认对象池正确回收
- 场景切换时释放资源
- 主动触发 `wx.triggerGC()`

### Q: 帧率低？
- 减少同屏对象数量
- 合并 Draw Calls
- 降低粒子特效数量
- 优化碰撞检测算法

---

## 📞 支持资源

### 官方文档
- [微信小游戏文档](https://developers.weixin.qq.com/minigame/dev/guide/)
- [Cocos Creator 文档](https://docs.cocos.com/creator/3.8/manual/zh/)
- [微信广告接入](https://developers.weixin.qq.com/minigame/dev/ad/)

### 社区
- [Cocos 论坛](https://forum.cocos.org/)
- [微信开放社区](https://developers.weixin.qq.com/community/)

### 工具
- [TinyPNG](https://tinypng.com/) - 图片压缩
- [Audacity](https://www.audacityteam.org/) - 音频编辑
- [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)

---

## 🎯 上线清单

### 开发阶段
- [ ] 核心玩法完成
- [ ] UI/UX 优化
- [ ] 音频系统
- [ ] 存档系统
- [ ] 广告接入

### 测试阶段
- [ ] 模拟器测试通过
- [ ] iOS 真机测试
- [ ] Android 真机测试
- [ ] 低端机测试
- [ ] 广告展示测试

### 优化阶段
- [ ] 包体 < 20MB
- [ ] 启动时间 < 3s
- [ ] FPS 稳定 60
- [ ] 内存 < 200MB
- [ ] 无崩溃 bug

### 提审准备
- [ ] 5张截图
- [ ] 游戏简介
- [ ] 分类选择
- [ ] 隐私政策（如需要）
- [ ] 版本号更新

### 发布后
- [ ] 监控留存率
- [ ] 监控广告收入
- [ ] 收集用户反馈
- [ ] 规划下一版本

---

**祝开发顺利！** 🚀