游戏引擎 / 系统课时

资源与本地存储如何统一

资源与本地存储如何统一

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 或小游戏文件路径。

ts
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);
    }
  }
}

预期输出(资源存在且写入成功):

text
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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

资源与本地存储如何统一

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通