bit-minigame：微信/支付宝/字节跳动小游戏，一套接口写完

它解决什么问题

同一款小游戏要同时发微信、支付宝、字节跳动，业务逻辑（广告、支付、分享）是一样的，但每个平台的 API 名字、参数、回调形式都不一样。最常见的写法是业务代码里到处塞 if (isWX) {...} else if (isAlipay) {...} else if (isBytedance) {...}，平台一多，这种判断散落得到处都是，加一个新平台或者某个平台 API 升级了，要把这些判断全部找出来改一遍。

bit-minigame 把三个平台的差异封装到统一接口后面，业务代码只调 MiniHelper，不用关心背后跑的是哪个平台的 SDK。

安装

bit-core 是 peer 依赖（用它的 Platform 做平台检测）：

npm install @gongxh/bit-minigame @gongxh/bit-core

核心用法

统一入口

import { MiniHelper } from '@gongxh/bit-minigame';

const common = MiniHelper.common();
const ad = MiniHelper.ad();
const pay = MiniHelper.pay();

通用信息

const launchOptions = common.getLaunchOptions(); // 冷启动参数，处理分享邀请常用
const hostVersion = common.getHostVersion();       // 微信/支付宝/抖音的宿主版本号
const { width, height } = common.getScreenSize();

激励视频广告

ad.showRewardedVideoAd({
    adUnitId: 'xxx-xxx-xxx',
    onComplete: () => giveReward(),  // 看完了才给奖励
    onError: (errCode, errMsg) => console.log('广告加载失败', errCode, errMsg),
    onClose: () => console.log('广告关闭'),
});

广告位 ID 要在各平台后台单独申请，一个 ID 只能在申请的那个平台用。实际项目里建议提前预加载广告，用户点击”看视频得奖励”的瞬间才开始加载的话，加载失败率会明显更高，用户体验也差。

支付

pay.init(offerId, unitPriceQuantity); // offerId 在不同平台含义不同（商户号/AppId）

pay.pay({
    rmb: 6,
    orderId: 'order_20260807_001',
    shopId: 'gold_pack_1',
    shopName: '100 金币礼包',
    sandbox: 0, // 0 正式环境，1 沙盒环境
    success: (res) => console.log('支付成功', res),
    fail: (res) => console.log('支付失败', res),
});

支付结果必须在服务器端二次验证，客户端的 success 回调只能当作”用户看到了成功提示”，不能当作发货依据——伪造客户端回调的成本比伪造服务端签名低得多。

平台判断

平台判断走 bit-core 的 Platform，不需要 bit-minigame 自己再定义一套：

import { Platform } from '@gongxh/bit-core';

if (Platform.isWX) {
    // 微信小游戏专属逻辑
} else if (Platform.isAlipay) {
    // 支付宝小游戏
} else if (Platform.isBytedance) {
    // 字节跳动小游戏
}

避坑提醒

  • 支付的 offerId 参数在不同平台代表的东西不一样（有的是商户号，有的是 AppId），照抄一个平台的配置传到另一个平台，接口大概率直接报错，接入新平台时要单独确认这个字段的含义。
  • 广告加载失败是常态而不是异常，尤其是网络不好或者广告库存不足的时候，onError 回调一定要处理，不能假设广告总能加载成功——没处理这个分支的话，用户点了”看广告”却什么都没发生，体验很差。
  • 测试支付流程一定要用沙盒环境（sandbox: 1），直接用正式环境测试容易产生真实扣款记录，退款流程比测试本身麻烦得多。

项目信息

这是 bit-framework 目前的最后一个模块介绍。12 个模块按需组合，具体怎么搭配可以回头看看总览文章里的依赖关系图。