游戏引擎 / 系统课时
localStorage 如何保存进度
localStorage 如何保存进度
玩家刷新页面后,Phaser 场景及其 Registry 会重新创建,运行时的通关记录也会消失。这里用浏览器 localStorage 保存最高已通关关卡和历史最高分,并为首次游玩、损坏数据和旧版本存档设置安全回退。
学习目标
- 定义带版本号、默认值与取值范围的存档结构。
- 使用
JSON.stringify、JSON.parse和校验函数安全保存、读取进度。 - 将持久化数据接入 Phaser Registry,并验证刷新与异常场景。
定义最小存档结构
假设游戏共 12 关,按顺序解锁。只保存需要跨刷新保留的数据,当前生命值、敌人对象和 Scene 实例不放进存档。
| 字段 | 默认值 | 含义与约束 |
|---|---|---|
version |
1 |
存档格式版本,旧版本不直接当新版本读取 |
clearedLevel |
0 |
已通关的最高关卡,整数 0~12;0 表示尚未通关 |
bestScore |
0 |
全游戏历史最高结算分,非负安全整数 |
存储键使用 phaser4-progress-demo;可以由 Math.min(12, clearedLevel + 1) 算出当前最高可进入关卡。例如 clearedLevel=2 时解锁第 3 关。重复通关低关卡或取得较低分数时,都不能把已保存的最高值覆盖成更小的数。
实现读取、校验与写入
加载时先读取字符串,再解析 JSON,最后检查对象类型、版本及字段范围。读取失败采用默认值;通关时使用 Math.max 合并旧记录后写入。写入异常不会阻止游戏继续运行,但需要提示本次未成功持久化。

在通过 http://localhost 或 HTTPS 打开的游戏页面中,按 F12 打开浏览器 Console,粘贴以下完整示例。它只使用浏览器原生 API,不要求 Phaser 已启动。
const SAVE_KEY = 'phaser4-progress-demo';
const LAST_LEVEL = 12;
function defaultProgress() {
return { version: 1, clearedLevel: 0, bestScore: 0 };
}
function validProgress(value) {
return value !== null && typeof value === 'object' &&
!Array.isArray(value) && value.version === 1 &&
Number.isInteger(value.clearedLevel) &&
value.clearedLevel >= 0 && value.clearedLevel <= LAST_LEVEL &&
Number.isSafeInteger(value.bestScore) && value.bestScore >= 0;
}
function loadProgress() {
try {
const raw = window.localStorage.getItem(SAVE_KEY);
if (raw === null) return defaultProgress();
const data = JSON.parse(raw);
if (!validProgress(data)) return defaultProgress();
// 仅保留约定的字段,忽略旧数据中的额外属性
return { version: 1, clearedLevel: data.clearedLevel,
bestScore: data.bestScore };
} catch {
return defaultProgress();
}
}
function saveProgress(progress) {
if (!validProgress(progress)) return false;
try {
window.localStorage.setItem(SAVE_KEY, JSON.stringify(progress));
return true;
} catch {
return false; // 存储权限受限或配额不足
}
}
function finishLevel(level, score) {
if (!Number.isInteger(level) || level < 1 || level > LAST_LEVEL ||
!Number.isSafeInteger(score) || score < 0) return false;
const previous = loadProgress();
return saveProgress({
version: 1,
clearedLevel: Math.max(previous.clearedLevel, level),
bestScore: Math.max(previous.bestScore, score)
});
}
// 以下仅用于演示,会重置此示例键并注入一条旧档
try {
window.localStorage.removeItem(SAVE_KEY);
console.log('默认', JSON.stringify(loadProgress()));
console.log('通关1', finishLevel(1, 900));
console.log('通关2', finishLevel(2, 700));
console.log('正常存档', JSON.stringify(loadProgress()));
window.localStorage.setItem(SAVE_KEY,
'{"version":0,"clearedLevel":"2","bestScore":700}');
console.log('旧档回退', JSON.stringify(loadProgress()));
} catch {
console.log('此环境禁止使用本地存储');
}预期输出(当前站点允许本地存储时):
默认 {"version":1,"clearedLevel":0,"bestScore":0}
通关1 true
通关2 true
正常存档 {"version":1,"clearedLevel":2,"bestScore":900}
旧档回退 {"version":1,"clearedLevel":0,"bestScore":0}version=0 且 clearedLevel 为字符串的旧档不会通过校验,因此回退为初始值。正式游戏应保留这些读写函数,但删掉末尾用于清空和注入旧档的测试代码;否则每次启动都会破坏存档。
与 Phaser 场景共享进度
localStorage 负责跨刷新持久化,Phaser 的 this.registry 负责本次运行中跨 Scene 共享。把上述函数放到项目的存档模块并按项目路径引入,首次进入游戏时读取一次,不要在每次重启关卡时都用磁盘值覆盖本局状态。
片段示例:以下放在游戏入口 Scene 的 create() 中,依赖已经引入的 loadProgress。
const progress = loadProgress();
this.registry.set('clearedLevel', progress.clearedLevel);
this.registry.set('bestScore', progress.bestScore);预期结果:其他 Scene 调用 this.registry.get('clearedLevel') 和 this.registry.get('bestScore'),可读取相同进度。
片段示例:以下放在关卡通关结算回调中;levelNumber 是实际通关编号(1~12),finalScore 是本次非负整数结算分,二者由现有游戏逻辑提供。
if (!Number.isInteger(levelNumber) || levelNumber < 1 ||
levelNumber > 12 || !Number.isSafeInteger(finalScore) ||
finalScore < 0) throw new Error('非法结算数据');
const next = {
version: 1,
clearedLevel: Math.max(this.registry.get('clearedLevel'), levelNumber),
bestScore: Math.max(this.registry.get('bestScore'), finalScore)
};
// 先保留本局结果,再尝试跨刷新持久化
this.registry.set('clearedLevel', next.clearedLevel);
this.registry.set('bestScore', next.bestScore);
if (!saveProgress(next)) {
console.warn('存档未写入,本次运行仍保留进度');
}预期结果:假设原本已通关第 1 关、最高分 900,本次完成第 2 关得到 700 分,则共享状态和成功写入的存档均为 clearedLevel=2、bestScore=900。写入失败时 Registry 仍保存本局结果,但关闭或刷新页面后无法保证恢复。
验证恢复与异常边界
- 删掉演示中的清空、注入旧档代码,正常通关两关后刷新页面,检查
loadProgress()是否仍读出2和900;在 Chrome DevTools 的 Application → Storage → Local Storage 中也能查看存储键。 - 将该键的值手动改成不完整 JSON(例如
{),再执行loadProgress(),应返回version=1、clearedLevel=0、bestScore=0,而不是导致启动报错。 - 模拟存储被禁用或配额不足:
saveProgress()返回false,游戏应允许继续游玩,并显示“本次进度无法保存”的提示。
用“启动读取并校验、通关合并并写入、写入失败保留本局状态”的职责划分,就能把本地存档与 Phaser 场景生命周期解耦。