前后台生命周期与本地文件
适用:引擎无关的生命周期原则,微信接口由官方类型与示例核对;客户端目标 Cocos Creator 3.8.8 + TypeScript。资料核查:2026-11-17。已核对前后台监听、解绑与文件系统的官方原文,未进行真机行为实测。
后台不是游戏里的暂停按钮
玩家切出微信、拉起系统界面或进入某些平台能力时,游戏可能失去可见性,之后恢复、重启,甚至没有机会执行最后一次保存。后台期间计时器与网络连接的表现不应被当作稳定承诺。游戏必须把“暂时不可见”和“会话已结束”分开设计,也不能依赖退出回调才写入全部进度。
对于本地战斗,失去可见性时清空按住状态、停止接受输入并暂停适合暂停的模拟;恢复时展示明确的继续入口,避免角色在玩家看清画面前受伤。对于实时房间,服务端通常仍在推进,客户端恢复后应重新同步,不能把本地暂停时长加回权威世界。挂机收益、体力恢复与活动截止由可信时间计算,不靠后台逐秒累加计时器。
只绑定一次,并保留解绑函数
平台级生命周期监听适合由应用入口统一管理,再转换为业务事件。每次进入战斗场景都绑定 wx.onShow,而离开时不解绑,会让恢复流程执行多次,表现为音乐叠加、连接重复和奖励查询重复。解绑时要使用同一个函数对象,不能新建一个内容相同的箭头函数。
interface VisibilitySource {
onShow(fn: () => void): void;
offShow(fn: () => void): void;
onHide(fn: () => void): void;
offHide(fn: () => void): void;
}
function bindVisibility(api: VisibilitySource,
changed: (visible: boolean) => void) {
const show = () => changed(true);
const hide = () => changed(false);
api.onShow(show); api.onHide(hide);
return () => { api.offShow(show); api.offHide(hide); };
}
示例展示监听所有权,不意味着平台回调只有这两个维度。启动参数与恢复参数还可能携带入口上下文,处理时需要去重和校验。入口 query 属于外部输入,不能凭其中的 reward=100 就发奖,也不能允许它任意切到内部调试页面。复用入口路由时区分冷启动初始化与已运行会话的意图更新。
恢复时从状态决定下一步
恢复不等于无条件重新登录、重新加载整张地图。保存离开前的应用阶段与世代,恢复后检查会话、房间、资源与界面是否仍有效:本地暂停局可继续;过期房间请求最终结果;加载中的场景需要判断旧请求是否仍应落地。一个总的 resume() 若顺序不清,会同时触发多条互相覆盖的异步链。
清空输入尤为重要。触摸开始后切后台,未必能按预期收到对应结束事件;继续沿用“摇杆向右”的状态会让恢复后的角色自动跑动。把输入状态重置设计成可重复调用的操作,同时取消拖动、长按和临时按钮锁。音频恢复要遵守用户静音设置,不应每次 onShow 都把背景音乐强制打开。
文件分为可再生缓存与不可丢状态
资源缓存能重新下载;玩家设置可以本地持久化;经济资产应来自服务端。临时路径、用户目录与包内文件各有生命周期,不要把下载接口返回的临时文件路径当成永久地址。包内内容通常作为构建资源读取,写入应使用平台允许的存储或文件接口。具体容量和清理规则需要当前平台文档核验,本课程不写猜测的统一上限。
存档保存一个版本化结构,记录 schemaVersion、revision 与业务内容。先序列化并检查大小,再通过受控的存储适配器写入;读取时做格式验证、迁移和损坏恢复。频繁操作不宜每帧同步写磁盘,可以按关键进度与节流策略保存,但关键奖励提交不能只存在内存里等待最终退出。存储失败应保留当前运行状态并给出可恢复路径。
type LocalSettings = { schemaVersion: 1; music: boolean; sfx: boolean };
function parseSettings(raw: unknown): LocalSettings | undefined {
if (!raw || typeof raw !== 'object') return;
const v = raw as Record<string, unknown>;
if (v.schemaVersion !== 1 || typeof v.music !== 'boolean' ||
typeof v.sfx !== 'boolean') return;
return { schemaVersion: 1, music: v.music, sfx: v.sfx };
}
格式合法也不代表内容可信,这类本地设置可直接使用,余额不能同样处理。不要在损坏恢复时顺便重置所有云进度;记录错误类别与版本,保留有用的备份或服务端恢复入口。多字段写入需要考虑中途失败,尽量以一个完整版本化对象提交;多文件方案则需要清单、临时文件与提交标记等明确协议。
缓存清理与场景释放是两回事
删除本地下载缓存不会释放已在内存中的纹理;销毁节点也未必删除磁盘文件。把文件缓存、引擎资源缓存、解码数据与 GPU 对象分别观察。清理策略优先清可再生、长期不用且当前未被加载流程使用的内容,不能一键清空用户目录。Cocos 的资源缓存管理器已有平台适配,业务再实现一套下载缓存容易产生索引与文件不一致。
失败排查要记录路径类别、资源版本、错误码与剩余流程,而不把用户目录所有内容打印进日志。存档“偶尔丢失”需分别模拟强制结束、写入失败、版本迁移和清理动作;只测试正常返回首页无法覆盖后台终止。开发者工具与真机的存储环境也应各自清理与复测,不能共享一次成功结论。
关键进度用检查点保存
关卡解锁、完成教学和确认领取等状态变化,应在各自完成时建立检查点,避免把整局数据只留在退出路径。检查点保存也不能阻塞每帧模拟:把必要状态快照化,再交给受控写入队列,并定义失败后是否重试或提示。写入队列结束前对象若销毁,队列仍需有稳定所有者,不能依附一个即将离开的节点。
同时准备从未完整保存过的情况。首次运行默认值应可用,旧版本缺字段应迁移,损坏数据不能让程序在启动循环报错。不要为了自动修复把所有异常都当空存档;未知的新版本需要保护,避免旧客户端覆盖它。恢复默认设置与恢复游戏资产属于不同权限和流程。
交给 AI 的任务与验收
可复制任务:“实现生命周期协调器与本地设置存储,业务层只订阅可见性。切后台清空输入,恢复按当前阶段处理;设置读入做版本验证,模拟写入失败与损坏。监听有明确解绑,资源缓存不与存档一起删除,日志不记录敏感内容。”
验收连续切换场景与前后台后监听数量不增长;按住摇杆切出后恢复角色静止;损坏设置回退到默认且不清空服务端资产;旧异步加载不能覆盖新场景。浏览器模拟先证明状态机,真机再记录后台恢复、音频和存储结果,两者分别列证据。
官方来源
-
微信官方 API 类型:onShow/onHide、存储与 FileSystemManager 接口;核对提交 42c427aa8c3961b7a4f8ea5bd6112c2bcf058177。
-
微信官方 game.js:启动与恢复入口的示例。
-
Cocos 3.8 缓存管理器:平台文件缓存的引擎管理入口;容量等政策须另核当前微信文档。
-
微信文件系统:已核对包内只读、临时路径与跨冷启动持久化边界。