游戏引擎 / 系统课时
登录能力怎样兼容多个平台
登录能力怎样兼容多个平台
同一套 Cocos Creator 3.8 游戏发布到 Web、原生应用和微信小游戏后,拿到的登录凭证、SDK 回调和恢复时机都不同。本课把差异关进平台适配器,让大厅、背包和存档模块只依赖统一会话。
学习目标
- 区分平台临时凭证与游戏服务端签发的会话。
- 实现可替换的登录适配器和会话状态管理。
- 处理登录失败、过期、前后台切换与重新登录。
凭证不同,会话却要相同
不要让业务模块分别解析微信 code、原生 SDK 票据和 Web 表单结果。它们只是证明身份的输入,并不是可以直接用于游戏接口的统一访问令牌。
| 运行环境 | 客户端获取的内容 | 服务端职责 |
|---|---|---|
| Web | 用户提交的账号凭据或 OAuth 授权结果 | 校验凭据或授权结果 |
| 微信小游戏 | wx.login 返回的临时 code |
向微信服务端兑换并校验身份 |
| Android/iOS 原生 | 所接渠道 SDK 的授权码或身份票据 | 按渠道规则验证签名、受众与有效期 |
三种方式最终都由游戏自己的服务端返回同一数据结构:userId、accessToken、expiresAtMs。其中 expiresAtMs 是毫秒时间戳;业务层只判断会话是否有效,不依赖 openid 或某个渠道字段。原生平台是否有静默登录,取决于实际接入的渠道 SDK,不能假设所有原生包都有同一个登录 API。
从平台入口到统一会话
登录界面向 LoginAdapter 索要凭证,再交给 AuthGateway 请求服务端验证;只有服务端验证成功,SessionService 才把状态从 authorizing 改成 authenticated。微信 code 应一次性尽快使用,既不作为业务 Token,也不写入持久化存储。

在 Cocos Creator 中验证适配器
新建 CrossPlatformLoginDemo.ts,挂到场景内任意激活节点。示例的 Web 通道和服务端兑换使用显式模拟实现,可在编辑器预览中验证状态变化;微信通道则调用真实 wx.login 获取临时凭证。原生渠道必须另外注入对应 SDK 适配器。
import { _decorator, Component } from 'cc';
import { NATIVE, WECHAT } from 'cc/env';
const { ccclass } = _decorator;
// 未引入微信类型包时,为小游戏入口补充最小声明。
declare const wx: {
login(options: {
success: (res: { code?: string }) => void;
fail: (err: unknown) => void;
}): void;
};
type Proof = { provider: 'web' | 'wechat'; credential: string };
type Session = { userId: string; accessToken: string; expiresAtMs: number };
type State = 'signedOut' | 'authorizing' | 'authenticated' | 'expired' | 'error';
interface LoginAdapter {
getProof(): Promise<Proof>;
}
class WebDemoAdapter implements LoginAdapter {
async getProof(): Promise<Proof> {
// 仅用于验证接线;正式 Web 登录由表单或 OAuth 提供真实凭据。
return { provider: 'web', credential: 'local-demo' };
}
}
class WechatAdapter implements LoginAdapter {
getProof(): Promise<Proof> {
return new Promise((resolve, reject) => {
wx.login({
success: (res) => res.code
? resolve({ provider: 'wechat', credential: res.code })
: reject(new Error('登录未返回 code')),
fail: reject,
});
});
}
}
class DemoGateway {
async exchange(proof: Proof): Promise<Session> {
// 模拟服务端响应,不做真实身份校验。
if (!proof.credential) throw new Error('缺少登录凭证');
return {
userId: 'demo-user',
accessToken: 'DEMO_ONLY',
expiresAtMs: Date.now() + 60000,
};
}
}
class SessionService {
state: State = 'signedOut';
session: Session | null = null;
async login(adapter: LoginAdapter): Promise<Session> {
this.state = 'authorizing';
try {
const proof = await adapter.getProof();
const next = await new DemoGateway().exchange(proof);
if (!next.accessToken || next.expiresAtMs <= Date.now()) {
throw new Error('会话无效或已过期');
}
this.session = next;
this.state = 'authenticated';
return next;
} catch (err) {
this.session = null;
this.state = 'error';
throw err;
}
}
isActive(): boolean {
if (this.session && Date.now() >= this.session.expiresAtMs) {
this.session = null;
this.state = 'expired';
}
return this.state === 'authenticated';
}
logout(): void {
this.session = null;
this.state = 'signedOut';
}
}
@ccclass('CrossPlatformLoginDemo')
export class CrossPlatformLoginDemo extends Component {
start(): void {
if (NATIVE) {
console.log('原生端请接入对应渠道的 LoginAdapter');
return;
}
const adapter = WECHAT ? new WechatAdapter() : new WebDemoAdapter();
const auth = new SessionService();
void auth.login(adapter).then((session) => {
console.log(`state=${auth.state}, user=${session.userId}, active=${auth.isActive()}`);
auth.logout();
console.log(`state=${auth.state}`);
}).catch((err) => console.error('login failed', err));
}
}预期输出(Web 编辑器预览):
state=authenticated, user=demo-user, active=true
state=signedOut过期、切后台与异常怎么处理
会话状态至少区分未登录、授权中、已登录、已过期和错误。页面恢复前台时,平台适配层发出统一恢复事件;会话层检查本地过期时间,必要时调用后端刷新或重新授权。本地时间检查只能做快速判断,服务端才是权限是否有效的最终依据。
验收时依次模拟重复点击登录、用户取消授权、SDK 返回空凭证、断网、Token 过期、切后台再恢复和主动退出。登录请求未结束时禁用重复提交;失败要清理过期会话并允许重试,不能把上次成功用户残留在 UI。敏感凭证不要写入普通日志,长期凭证只应保存在经安全设计的服务端或平台安全存储中。