# 故意迁移旧的保存形状

> 确定如何读取旧版本游戏保存的数据，并在使用已知格式的数据前完成迁移。

- URL: https://oneshotgems.ai/zh-Hans/topics/local-storage-game-versioning
- 类别: 游戏开发者指南
- 类型: 指南
- 更新日期: 2026年10月5日

保存状态测试询问预期值是否持续存在。版本控制回答了另一个问题：当较新的游戏版本读取较旧版本写入的数据时会发生什么？如果版本一将最佳分数存储为数字，而版本二存储配置文件对象，则像新形状一样读取旧形状可能会破坏菜单或默默地放弃进度。将版本放在保存的数据旁边，并为已知的早期形状编写显式迁移。

## 将数据保存在精简的版本化对象中

不要保存诸如 240 之类的裸分数，而是存储一个 JSON 对象，例如 { version: 2, bestScore: 240, settings: { sound: true } }。加载时，解析文本，检查它是否是一个对象，并在使用字段之前检查其版本。 JSON.parse 可能会因无效 JSON 引发 SyntaxError，因此使用定义的后备处理格式错误的文本，而不是允许启动在播放器开始之前停止。

保持数据对象精简，并记录每个版本的含义。不要把版本号本身当作充分验证：标记为版本 2 的值仍可能不完整或类型错误。检查当前版本实际依赖的字段，例如 bestScore 必须是有限的非负数，声音偏好必须是布尔值。

## 为每种受支持的旧格式编写迁移

从版本 1 迁移时，可以将旧数字转换为新对象、补上默认设置，再按版本 2 的格式保存。如果支持多个历史版本，应按顺序迁移：从版本 1 到 2，再从 2 到 3。分别测试每个测试用例，包括缺失的键、格式错误的 JSON、未知的未来版本以及只写入了一部分的值。决定如何保留、忽略或重置未知数据，并在需要时显示恢复提示。

## 了解浏览器存储的限制

MDN 将 localStorage 描述为与来源关联、可能跨浏览器会话保留的数据。但存储是否可用、内容是否仍在，都不能视为有保障的账户备份。不要在其中保存秘密或需要可信保障的决策。如果游戏无法读取存档，应允许从已定义的初始状态开始，并避免每次启动都重复尝试同一个失败的迁移。

## 常见问题

**当格式改变时我应该清除所有保存吗？** 仅当这是明确的产品决策时。如果可以安全地映射重要值，则经过测试的小型迁移可以保留它们；否则定义明确的后备并解释重置。

**版本字段是否使 localStorage 数据可靠？** 不会。它会识别预期的形状，以便游戏可以迁移或拒绝它。数据仍然可能丢失、格式错误、过时或不可用，因此在使用之前请进行验证。

## 跟随好奇心探索

- [在浏览器游戏中测试保存状态](https://oneshotgems.ai/zh-Hans/topics/testing-game-save-state): 验证浏览器游戏保存的内容、重置的内容，以及当存储的数据丢失、过时或在会话之间发生更改时它的行为方式。
- [小型游戏的回归测试循环](https://oneshotgems.ai/zh-Hans/topics/game-regression-testing): 使用专注于机制、得分、重新启动和附近边缘情况的简短回归检查表来保护修改后的游戏循环。

## 延伸阅读

- [MDN 本地存储](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
- [MDN JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)

---
规范页面: https://oneshotgems.ai/zh-Hans/topics/local-storage-game-versioning