游戏引擎 / 系统课时
平台判断代码该放在哪里
平台判断代码该放在哪里
Cocos Creator 3.8 项目发布到 Web、微信小游戏与原生端时,登录、分享和前后台通知由不同宿主提供。若界面中散落平台判断,改一个渠道就会牵动玩法代码。本课将判断集中到适配器创建入口,让业务只依赖稳定的能力契约。
学习目标
- 区分核心业务、平台能力接口与具体 SDK 的职责。
- 使用
cc/env的平台常量在单一入口选择实现。 - 验证浏览器、微信小游戏和未接入原生能力时的不同行为。
业务只表达要做什么
角色和 UI 只需提出“发起登录”“请求分享”或“监听返回前台”,不应调用 wx.login、浏览器 API 或原生桥接。把平台检查分散在按钮回调里,不仅难以模拟测试,也容易在 Web 端误引用不存在的 wx 全局对象。
建议把业务可见的抽象称为 PlatformPort,由 WebPlatform、WechatPlatform、NativePlatform 分别实现。仅在应用启动或依赖组合处选择实现,之后所有业务通过同一对象访问能力;SDK 的错误和返回值也在这一层转换成统一结果。

以登录为例定义最小接口
先统一业务真正需要的结果,如登录通道和可选的临时凭证,而不是直接把微信 SDK 的整个回调对象交给界面。Web 预览可返回访客状态;微信实现调用 wx.login 获取一次性 code。这段凭证必须交给可信服务端换取会话,不能当作玩家 ID,也不能写进日志。
下面是可放入项目脚本的完整示例。将 PlatformLoginDemo 组件挂到启动场景内的活动节点;WECHAT、NATIVE 和 HTML5 是 Cocos Creator 3.8 的 cc/env 构建环境常量,不是自行拼写的平台字符串。
import { _decorator, Component, error, log } from 'cc';
import { HTML5, NATIVE, WECHAT } from 'cc/env';
const { ccclass } = _decorator;
type LoginResult = { channel: 'guest' | 'wechat'; code?: string };
interface PlatformPort {
login(): Promise<LoginResult>;
}
// 未引入微信类型包时,声明本示例所用的最小宿主接口
declare const wx: {
login(options: {
success: (result: { code?: string }) => void;
fail: (reason: unknown) => void;
}): void;
};
class WebPlatform implements PlatformPort {
async login(): Promise<LoginResult> {
return { channel: 'guest' };
}
}
class WechatPlatform implements PlatformPort {
login(): Promise<LoginResult> {
return new Promise((resolve, reject) => {
wx.login({
success: ({ code }) => {
if (!code) return reject(new Error('微信未返回登录 code'));
// 保留临时凭证供业务层交给服务端,不直接认定已登录
resolve({ channel: 'wechat', code });
},
fail: reject,
});
});
}
}
function createPlatform(): PlatformPort {
if (WECHAT) return new WechatPlatform();
if (NATIVE) {
// 未实现的渠道显式失败,不能悄悄伪装为 Web 访客
return { login: () => Promise.reject(new Error('原生适配器尚未接入')) };
}
if (HTML5) return new WebPlatform();
return { login: () => Promise.reject(new Error('当前平台尚未接入')) };
}
@ccclass('PlatformLoginDemo')
export class PlatformLoginDemo extends Component {
start(): void {
createPlatform().login()
.then(result => log(`登录通道:${result.channel}`))
.catch(reason => error('登录失败', reason));
}
}预期输出(Web 预览控制台):
登录通道:guest微信小游戏宿主中 wx.login 成功返回 code 时输出 登录通道:wechat;失败时走错误分支。当前原生分支刻意报出“原生适配器尚未接入”,提醒开发者接入渠道 SDK,而不是把访客模式错误地当成正式原生登录。这里的 Web 访客模式也不代表真实账户认证成功。
新增平台时修改哪里
新增 iOS/Android 原生登录时,只需编写实现 PlatformPort 的 NativePlatform,在工厂的 NATIVE 分支注入它,界面不需要改变。分享、后台恢复等能力同理,但应分别声明参数、成功结果、取消与失败的语义,并在订阅型接口返回取消订阅方法以避免重复回调。
支付、实名认证等安全敏感能力建议另设独立接口:客户端只负责发起流程和展示结果,订单真实性及最终支付状态必须由服务端确认。平台差异应集中在组合入口与适配实现,而不是由每个业务模块重复判断。