游戏引擎 / 系统课时
资源与本地存储如何统一
资源与本地存储如何统一
Cocos Creator 3.8 的 Web、原生和小游戏构建产物并不共享文件路径、缓存目录或浏览器 API。解决办法不是让业务代码到处判断平台,而是分别封装资源加载和键值存储,让调用方只关心资源标识与用户数据。
学习目标
- 区分游戏资源、引擎下载缓存和玩家本地数据。
- 使用
resources.load与sys.localStorage构建两个稳定入口。 - 验证路径、存储配额、版本升级及远程资源的异常处理。
不要把缓存当成存档
资源与存储的生命周期不同。图片、Prefab、音频由资源系统按需加载并管理内存引用;音量、语言等设置是按键读写的数据;玩家核心进度如果需要跨设备恢复,还应有服务端权威副本。
| 内容 | 建议入口 | 特点 |
|---|---|---|
| 包内图片、Prefab | resources.load 或 Bundle 的 load |
用工程资源路径,不拼接宿主绝对路径 |
| 远程关卡包 | assetManager.loadBundle |
依赖地址、版本、网络和引擎缓存 |
| 小型本地设置 | sys.localStorage |
键值字符串,适合 JSON 序列化 |
| 大文件、下载目录 | 独立平台文件适配器 | 不同宿主文件系统与配额差异明显 |
sys.localStorage 在 Web 使用浏览器存储机制,在原生运行时由引擎提供持久化实现;小游戏应经引擎适配层使用,并在目标真机上检查配额与清除行为。引擎对下载资源的缓存不等于用户存档,清缓存不应丢失账号进度。
把差异放到两个入口之后
业务层向 SettingsStore 保存结构化配置,向 SpriteAssetPort 索要 SpriteFrame;前者处理序列化和键名版本,后者负责加载成功或失败。未来换成远程 Bundle、渠道文件 API,变化也留在各自实现内,不扩散到 UI。

用一个组件验证两种调用
先在 assets/resources/ui/ 放入 icon.png,确认导入后存在 SpriteFrame 子资源;在 Canvas 下创建带 Sprite 组件的节点,再把 ContentAndStorageDemo.ts 挂在同一节点。示例只使用 Cocos 3.8 跨平台引擎接口,不使用浏览器 window.localStorage 或小游戏文件路径。
import { _decorator, Component, resources, Sprite, SpriteFrame, sys } from 'cc';
const { ccclass } = _decorator;
type Settings = { music: boolean; lang: 'zh' | 'en' };
class SettingsStore {
private readonly key = 'demo:settings:v1';
save(value: Settings): void {
// 存储接口写入字符串;用版本键避免未来结构冲突。
sys.localStorage.setItem(this.key, JSON.stringify(value));
}
load(): Settings {
const fallback: Settings = { music: true, lang: 'zh' };
const raw = sys.localStorage.getItem(this.key);
if (raw === null) return fallback;
try {
const value = JSON.parse(raw) as Partial<Settings> | null;
if (value && typeof value.music === 'boolean' &&
(value.lang === 'zh' || value.lang === 'en')) {
return { music: value.music, lang: value.lang };
}
} catch {
// 旧版本或损坏数据不应导致游戏启动失败。
}
return fallback;
}
}
class SpriteAssetPort {
load(path: string): Promise<SpriteFrame> {
return new Promise((resolve, reject) => {
resources.load(path, SpriteFrame, (err, asset) => {
if (err || !asset) {
reject(err ?? new Error('未找到 SpriteFrame'));
return;
}
resolve(asset);
});
});
}
}
@ccclass('ContentAndStorageDemo')
export class ContentAndStorageDemo extends Component {
start(): void {
void this.verify();
}
private async verify(): Promise<void> {
try {
const store = new SettingsStore();
store.save({ music: false, lang: 'zh' });
const saved = store.load();
console.log(`music=${saved.music}, lang=${saved.lang}`);
const sprite = this.getComponent(Sprite);
if (!sprite) throw new Error('当前节点缺少 Sprite 组件');
// SpriteFrame 子资源路径不带 png 扩展名。
sprite.spriteFrame = await new SpriteAssetPort().load('ui/icon/spriteFrame');
console.log('sprite loaded');
} catch (err) {
console.error('verify failed', err);
}
}
}预期输出(资源存在且写入成功):
music=false, lang=zh
sprite loaded同时画面中该 Sprite 会显示 icon.png 的图像。若先出现 verify failed,优先检查节点组件和 assets/resources/ui/icon.png 的导入结果,不要把资源面板看到的文件系统路径直接传给 resources.load。
迁移到分包及异常处理
当资源从内置 resources 迁到 ui Bundle 时,改由资源入口调用 assetManager.loadBundle('ui', ...),再按相对路径 bundle.load(...);只有已经在项目中配置为 Bundle 的文件夹才能按名称加载。远程 Bundle 还要考虑平台合法域名、HTTPS、资源版本、断网回退和缓存清理策略,不宜用用户设置的 clear 操作顺手清空引擎缓存。
本地存储必须考虑配额不足、隐私模式、用户清数据和损坏的 JSON。写入失败应可报告且不妨碍游戏继续运行;读取失败使用默认配置;字段升级则迁移旧键后写入新版本。不要把支付凭证、服务端权威进度或长期认证密钥当普通设置写入 sys.localStorage。