游戏引擎 / 系统课时
让资源加载过程可失败
让资源加载过程可失败
资源路径拼错时,程序仍访问尚未得到的 SpriteFrame,就会把真正的加载错误掩盖成空值异常。本节为加载过程建立成功、失败与过期结果三条边界,先独立验证提交规则,再给出 Cocos resources.load 的真实接入与预览检查。
学习目标
- 将加载回调封装为能拒绝的 Promise。
- 在资源成功且请求仍有效时才更新表现。
- 验证路径错误与组件停用后的处理。
先明确何时可以提交结果
调用加载 API 后不会马上得到资源,必须在成功回调后使用它。失败应保留原错误并给界面一个可观察状态;不能只打印错误后继续访问空资源。与此同时,组件可能在等待期间停用,所以成功也需要确认这份结果仍属于当前有效请求。
可以用版本号表达请求归属:启动时记录版本,失效时递增版本,完成时比较。版本检查只阻止应用旧结果,并没有取消底层资源请求。资源仍可能进入引擎缓存,资源释放则需要根据引用所有权另外安排。

独立验证加载与提交规则
文件:main.ts,完整纯 TypeScript 程序,内存加载夹具只验证成功和失败分支。
export {};
async function loadAndApply(
load: (path: string) => Promise<string>, path: string,
apply: (asset: string) => void,
): Promise<string> {
try {
const asset = await load(path);
apply(asset);
return 'ready';
} catch (error: unknown) {
return error instanceof Error ? `failed:${error.message}` : 'failed:unknown';
}
}
async function main(): Promise<void> {
const load = async (path: string): Promise<string> => {
if (path !== 'hero') throw new Error('not found');
return 'hero-frame';
};
// 只有成功加载才会调用 apply。
let shown = 'placeholder';
console.log(await loadAndApply(load, 'hero', asset => { shown = asset; }));
console.log(await loadAndApply(load, 'missing', asset => { shown = asset; }));
console.log(shown);
}
void main().catch((error: unknown) => { throw error; });预期输出:
ready
failed:not found
hero-frame接入 SpriteFrame 资源
文件:SafeSkin.ts,片段示例,依赖 Creator 3.8、Sprite 组件与 resources 中的图片资源。
import { _decorator, Component, Sprite, SpriteFrame, resources, isValid } from 'cc';
const { ccclass, property } = _decorator;
function loadFrame(path: string): Promise<SpriteFrame> {
return new Promise((resolve, reject) => {
resources.load(path, SpriteFrame, (error, frame) => {
if (error) { reject(error); return; }
if (!frame) { reject(new Error('frame missing')); return; }
resolve(frame);
});
});
}
@ccclass('SafeSkin')
export class SafeSkin extends Component {
@property
path = 'skins/hero/spriteFrame';
private version = 0;
onEnable(): void {
const request = ++this.version;
void this.apply(request);
}
onDisable(): void { this.version += 1; }
private async apply(request: number): Promise<void> {
try {
const frame = await loadFrame(this.path);
// 成功也要检查组件与当前请求归属。
if (!isValid(this) || !this.enabledInHierarchy || request !== this.version) return;
const sprite = this.getComponent(Sprite);
if (!sprite) throw new Error('Sprite missing');
sprite.spriteFrame = frame;
console.log('skin ready');
} catch (error: unknown) {
if (request === this.version && isValid(this) && this.enabledInHierarchy) {
console.error(error instanceof Error ? error.message : 'load failed');
}
}
}
}预期结果:把一张可用图片导入 assets/resources/skins,命名为 hero,确认有 SpriteFrame 子资源;在 Canvas 下可见 Sprite 节点挂 SafeSkin,Inspector 保持默认路径。保存并预览,成功后显示该图片,并输出 skin ready。
按路径与时机分别验收
resources 路径相对 assets/resources,不带文件扩展名;图片的 SpriteFrame 子资源路径通常以 spriteFrame 结尾。把 path 改成不存在的值再预览,应有加载错误,原 Sprite 表现不被无效结果覆盖。具体引擎错误文本可能不同,不以固定字符串作为验收条件。
再以正确路径预览,在完成前停用组件,完成结果应被忽略;重新启用会启动新版本请求。缓存很快时不容易人工制造等待,应重点检查版本代码并通过后续竞态例程验证规则。不要人为宣称本地预览一定出现延迟或错误。
如果回调出错,先区分加载失败和应用失败:前者检查资源目录、路径和类型,后者检查 Sprite 是否存在、组件是否有效。这里 catch 统一报告,但原错误仍保留位置。资源引用释放需要结合其他使用者决定,不能为清理旧请求随意释放共享 SpriteFrame。
为了排查同一路径在不同实例上的问题,可以记录路径和请求版本,但不要为每帧打印加载状态。加载只在启用入口发起,结果只在完成时提交;这两个位置足以说明哪一次请求成功、哪一次被丢弃,以及错误发生在资源读取还是表现应用。
引擎路径与子资源规则见 Cocos 3.8 动态资源加载。本节的终端成功证明业务加载分支;真实资源导入与显示需要在 Creator 场景里验证。