游戏引擎 / 系统课时
小游戏平台 API 怎样做隔离
小游戏平台 API 怎样做隔离
同一款 Cocos Creator 3.8 游戏发布到微信、其他小游戏和网页时,直接在玩法脚本里调用 wx 会让功能迁移与测试都变得困难。本课把登录、分享、生命周期调用集中到平台适配器,并为支付保留独立的服务端确认边界。
学习目标
- 区分核心玩法、平台能力接口和渠道适配器的职责。
- 实现可在微信小游戏与浏览器预览间切换的登录、分享和前后台事件适配。
- 理解支付验证与事件注销为何不能留在普通玩法脚本里。
让业务依赖能力而不是渠道
玩家点击“登录”时,业务真正需要的是一个可交给服务端兑换登录态的凭据,而不是知道 wx.login 的参数。类似地,“邀请好友”是业务动作,微信分享面板才是渠道实现。直接散落 wx 调用会产生三类问题:网页预览报未定义、换渠道要修改多处、销毁场景后留下生命周期监听。
把依赖方向固定为:玩法组件调用 PlatformPort;创建游戏时选择 WechatPort 或 PreviewPort;适配器才可接触平台全局对象。支付单列 PaymentPort,避免把支付回调误当作订单已完成。

实现一个最小可用适配器
在项目脚本中新建 PlatformGatewayDemo.ts,挂到首场景的常驻测试节点上。示例只实现登录、主动分享和前台恢复,浏览器侧使用无鉴权的预览桩;支付接口仅定义契约,不会假装完成一笔交易。代码中的 WxSDK 是本例所用微信 API 的最小类型声明,并非独立的第三方库。
import { _decorator, Component } from 'cc';
const { ccclass } = _decorator;
type LoginResult = { channel: 'wechat'; code: string } | { channel: 'preview' };
interface PlatformPort {
login(): Promise<LoginResult>;
share(title: string): void;
onForeground(listener: () => void): () => void;
}
interface PaymentPort {
pay(serverOrderId: string): Promise<'confirmed' | 'cancelled'>;
}
type WxSDK = {
login(options: {
success: (res: { code?: string }) => void;
fail: (err: { errMsg?: string }) => void;
}): void;
shareAppMessage(options: { title: string }): void;
onShow(listener: () => void): void;
offShow(listener: () => void): void;
};
class WechatPort implements PlatformPort {
constructor(private readonly sdk: WxSDK) {}
login(): Promise<LoginResult> {
return new Promise((resolve, reject) => {
this.sdk.login({
success: ({ code }) => code
? resolve({ channel: 'wechat', code })
: reject(new Error('empty login code')),
fail: ({ errMsg }) => reject(new Error(errMsg || 'login failed')),
});
});
}
share(title: string): void {
this.sdk.shareAppMessage({ title });
}
onForeground(listener: () => void): () => void {
this.sdk.onShow(listener);
return () => this.sdk.offShow(listener); // 用同一函数引用解除监听
}
}
class PreviewPort implements PlatformPort {
async login(): Promise<LoginResult> {
return { channel: 'preview' }; // 不伪造微信登录凭据
}
share(title: string): void {
console.info('[preview] share:', title);
}
onForeground(_listener: () => void): () => void {
return () => {};
}
}
@ccclass('PlatformGatewayDemo')
export class PlatformGatewayDemo extends Component {
private readonly port: PlatformPort = (() => {
const sdk = (globalThis as typeof globalThis & { wx?: WxSDK }).wx;
return sdk ? new WechatPort(sdk) : new PreviewPort();
})();
private disposeShow: () => void = () => {};
start(): void {
this.disposeShow = this.port.onForeground(
() => console.info('[lifecycle] foreground')
);
void this.port.login()
.then(result => console.info('[login] channel:', result.channel))
.catch(error => console.warn('[login] failed:', error));
}
onShareTap(): void {
this.port.share('一起来玩');
}
onDestroy(): void {
this.disposeShow();
}
}预期输出:浏览器预览启动后,控制台打印:
[login] channel: preview构建为微信小游戏并成功取得临时登录凭据时,显示 [login] channel: wechat。把场景中的“分享”按钮点击事件绑定到 onShareTap,微信端应调起分享流程;浏览器端仅打印分享标题。微信登录码属于一次性临时凭据,应交由业务服务端交换会话,不能直接当玩家 ID,也不应打印码值。
把支付和生命周期当作边界
支付能力虽然也由渠道提供,但真正的业务结果是“后端已确认订单”。调用 PaymentPort.pay(serverOrderId) 前应先从服务端创建订单;渠道完成支付流程后,由服务端依据该渠道的交易规则核验订单,再向游戏返回 confirmed。渠道不支持支付或没有资质时,明确提示不可用,不能返回模拟成功;游戏不应仅凭客户端成功回调发放道具。
前后台事件不等于节点显示隐藏。wx.onShow 只负责通知小游戏回到前台;首次进入场景的初始化仍由 Cocos 组件生命周期负责。示例把 offShow 封装为清理函数,在 onDestroy 调用,避免反复进入场景后重复处理恢复事件。若使用持久化平台服务,监听应由服务创建一次,并在服务销毁时清理。
验收隔离是否有效
先在浏览器预览确认没有 wx is not defined,登录返回预览状态、按钮仅输出分享日志;再构建微信小游戏,确认登录成功时只把凭据交给服务端、分享由用户点击触发,切后台再返回仅打印一次恢复事件。最后切回浏览器,不修改任何玩法脚本就能继续运行,才算把渠道差异真正封装起来。