游戏引擎 / 系统课时
资源请求失败时怎样回退
资源请求失败时怎样回退
角色图片请求失败后,Phaser 的加载队列仍可能结束并进入 create()。如果直接创建依赖缺失纹理的对象,画面就会出错。这里以 Phaser 4.2.1 和 Vite 为例,实现失败资源清单、无需图片的回退画面和手动重试按钮,再用浏览器 Network 面板找出真正的失败原因。
学习目标
- 用
loaderror收集失败文件的key和请求地址,正确理解complete。 - 在
create()显示失败信息、占位图形及可点击的重试按钮。 - 区分静态资源路径错误与临时网络故障,并完成两种情况的验证。
先记录失败,再决定画面
场景在 preload() 中入队资源,Loader 逐个请求。单个文件失败时会触发 loaderror,回调参数是失败的 Phaser.Loader.File,可读取 file.key、file.src。队列结束时仍会触发 complete;它只表示本轮处理完毕,不保证每项成功。create() 随后执行,所以必须主动判断失败清单。
本例把失败记录放在场景的 this.failed 中,每次 init() 清空。按钮调用 this.scene.restart() 重新走场景生命周期;已经存在于 Texture Manager 的图片不再入队,避免同名纹理冲突。只有全部必需图片可用时才进入正常画面。

写出可以重试的加载场景
适用环境:Phaser 4.2.1、Vite 的 Vanilla JavaScript 模板,以及满足当前 Vite 运行要求的 Node.js。先创建项目并安装固定版本的 Phaser:
npm create vite@latest phaser-retry-demo -- --template vanilla
cd phaser-retry-demo
npm install
npm install phaser@4.2.1预期结果:目录 phaser-retry-demo 创建完成,依赖安装结束且没有错误退出。不同 npm 版本的安装日志可能不同。
把 src/main.js 完整替换为以下代码。它请求两张必需图片;即使 public/assets/ 中还没有图片,场景本身仍能运行并展示错误页面。
import Phaser from 'phaser';
const images = [
{ key: 'hero', filename: 'hero.png' },
{ key: 'bg', filename: 'bg.png' }
];
class AssetScene extends Phaser.Scene {
constructor() {
super('AssetScene');
}
init() {
this.failed = [];
}
preload() {
// 已缓存的纹理跳过,重试时只加载缺失项。
const pending = images.filter(({ key }) => !this.textures.exists(key));
if (pending.length === 0) return;
const onError = (file) => {
this.failed.push({ key: file.key, url: file.src });
console.warn('加载失败:', file.key, file.src);
};
// 本轮加载完成后移除监听,防止重启时重复记录。
this.load.on('loaderror', onError);
this.load.once('complete', (_loader, ok, failed) => {
this.load.off('loaderror', onError);
console.info(`本轮加载:成功 ${ok},失败 ${failed}`);
});
for (const { key, filename } of pending) {
this.load.image(key, `${import.meta.env.BASE_URL}assets/${filename}`);
}
}
create() {
this.add.text(32, 24, '资源加载检查', {
fontSize: '28px', color: '#ffffff'
});
if (this.failed.length === 0) {
this.add.text(32, 88, '加载成功,开始游戏', {
fontSize: '20px', color: '#8ee4ce'
});
this.add.image(400, 220, 'bg').setDisplaySize(96, 96);
this.add.image(580, 220, 'hero').setDisplaySize(96, 96);
return;
}
this.add.text(32, 82, '失败资源(key / URL):', {
fontSize: '18px', color: '#ffb879'
});
this.failed.forEach(({ key, url }, index) => {
this.add.text(32, 128 + index * 38, `${key} / ${url}`, {
fontSize: '17px', color: '#ffffff'
});
});
// 失败界面只用程序生成的图形,不依赖外部图片。
this.add.rectangle(580, 220, 96, 96, 0x18a999);
this.add.text(580, 285, '占位图形', {
fontSize: '16px', color: '#ffffff'
}).setOrigin(0.5);
const retry = this.add.text(32, 325, '重试加载', {
fontSize: '22px', color: '#ffffff',
backgroundColor: '#167e77', padding: { x: 18, y: 10 }
});
retry.setInteractive({ useHandCursor: true });
retry.on('pointerdown', () => this.scene.restart());
}
}
new Phaser.Game({
type: Phaser.AUTO,
parent: 'app',
width: 800,
height: 450,
backgroundColor: '#15232d',
loader: { maxRetries: 2 },
scene: AssetScene
});预期结果:源码替换后,场景有成功与失败两种画面;失败时显示资源键及 URL、青绿色占位方块和“重试加载”按钮,不会尝试使用缺失的图片。maxRetries: 2 表示单个文件失败时最多额外重试两次,之后才报告最终失败。
启动 Vite:
npm run dev预期结果:终端给出本地访问地址(实际端口可能不同);打开该地址,如果两张图片都尚未放入 public/assets/,画面列出 hero、bg 两项失败资源,控制台在本轮结束后显示 本轮加载:成功 0,失败 2。
用请求证据区分路径和网络
按浏览器 F12 → Network(网络)→ 刷新页面,选中失败的图片请求。先看 Request URL,再看 Status 和 Response;loaderror 本身并不能可靠区分 HTTP 错误、跨域限制与断网。
| 观察结果 | 优先排查与处理 |
|---|---|
404 Not Found |
检查大小写、文件名和部署前缀;Vite 的 public/assets/hero.png 在站点根路径部署时对应 /assets/hero.png,不是 /public/assets/hero.png。 |
(failed)、net::ERR_INTERNET_DISCONNECTED 或超时 |
先恢复连接,查看 Console 是否提示 CORS 或请求被拦截,再尝试手动重试;网络失败不必然意味着文件不存在。 |
500、502、503 等 |
检查静态服务器或 CDN 服务状态,不要让按钮无限自动重试。 |
例子使用 import.meta.env.BASE_URL 拼接资源地址,让 Vite 配置了子路径 base 时也能生成对应前缀。发布前仍应通过构建产物所在的实际 URL 验证图片请求。
按失败、部分恢复和完全恢复验收
- 保持
public/assets/hero.png、public/assets/bg.png不存在,刷新页面。应看到两条失败项、回退方块和重试按钮;点击按钮后能再次请求,但失败项不会凭空消失。 - 新建
public/assets/,仅放入一张真实的hero.png,点击“重试加载”。此轮应为成功 1、失败 1;页面只列出bg,已成功的hero进入全局纹理缓存。 - 此时保持
bg缺失,在 Network 面板切到 Offline(离线)后点击重试,确认失败列表仍可显示;恢复 Online(在线),排除真实断网问题。 - 放入有效的
bg.png并点击按钮。此轮只需请求bg,控制台应显示成功 1、失败 0,场景显示“加载成功,开始游戏”以及两张图片。
按钮适合用户可控的重试;不要在 loaderror 回调里无条件立即重新入队,否则会反复请求永久错误的 URL。上线时应把影响游戏启动的纹理列为必需资源并阻止进入玩法,对非必需装饰图则可使用预先准备的程序绘制占位内容继续显示场景。