Godot 存档/读档系统实现：用版本化…

在 Godot 中实现玩家进度、设置与游戏状态的存档/读档与数据持久化时，用版本化序列化、备份与迁移保证存档安全可演进。

适用场景

解决思路

1. 每个存档数据块都必须包含 version 字段（如 "version": "1.0.0"），并在版本不一致时通过 save_migration_manager.gd 执行迁移后再加载。
2. 只使用 user:// 协议路径，绝不硬编码 C:/Users/... 等操作系统绝对路径。
3. 绝不直接保存 Node 引用；把位置、生命值、等级等原始数据抽取到 Dictionary 或 Resource 中再序列化。
4. 不要忘记关闭 FileAccess 句柄；Godot 4 中变量离开作用域会自动关闭，但长时间运行的逻辑应显式调用 close()。
5. 不要用 JSON 存储超大二进制数据（如 10MB 纹理的 Base64），改用二进制 store_var() 或独立资源文件。
6. 加载数据前必须校验：用 data.get("field", default_value) 取字段，并检查数值在预期范围内，防止用户改档导致崩溃。
7. 不要在高频物理或动画更新中触发保存；只在进入菜单、完成关卡或到达检查点等明确事件时保存。
8. 不要在遍历 Dictionary 键的同时修改它；用 data.duplicate() 安全迭代。
9. 绝不在未加密 JSON 中存储明文密码或敏感凭据；敏感数据用 FileAccess.open_encrypted_with_pass() 加密。
10. 不要在主线程用 ResourceLoader.load() 加载超大场景，改用 ResourceLoader.load_threaded_request() 后台加载。
11. 不要依赖 get_instance_id() 做跨会话标识，它每次重启都会变；为游戏对象生成自己的持久 String UUID。
12. 加载共享 Resource 属性块（如 goblin_stats.tres）后必须调用 duplicate(true)，否则多个敌人会共享同一生命池。
13. 对不可信数据绝不在 store_var/get_var 中启用 allow_objects 标志；默认始终使用 store_var(data, false) / get_var(false)，只有完全可信的本地工具数据才可设为 true 并记录原因。
14. 需要严格类型保留的数据不要用 JSON（JSON 会把 Vector3 转成字符串或字典）；改用 var_to_bytes() 或二进制格式。
15. 序列化前清理 Dictionary 中的内部元数据（set_meta），避免存档体积膨胀。
16. 写 SaveManager 代码前，先阅读所选格式对应的脚本：JSON/二进制/PERSIST 收集用 save_load_patterns.gd，版本迁移用 save_migration_manager.gd，加密槽位用 save_system_encryption.gd，完整性校验用 save_integrity_validator.gd。
17. JSON 中存储 Vector3 时拆成 {x,y,z} 分量，因为 JSON 无法忠实往返 Vector3。
18. 覆盖主存档前先滚动备份：用 DirAccess.copy_absolute 复制为 .bak，防止写入中途崩溃损坏主文件。
19. 采用黄金路径：版本字段 → 版本不同则迁移 → 覆盖前备份 → 写入临时文件再重命名（或先备份后写入）并校验打开错误 → 可选用 FileAccess.get_sha256 比对完整性，不匹配则回退备份 → 仅用 user:// 路径 → 只在菜单/检查点/关卡完成时保存。
20. 设置类数据可单独用 ConfigFile（如 user://settings.cfg）保存，与运行进度的 JSON/二进制分开。
21. 按需求选择持久化形态：人类可读的小中型进度用 JSON + version；类型忠实的 Variant 或较大数据块用二进制 store_var 且 allow_objects=false；类型化 Resource 树用 ResourceSaver/.tres/.res；大量场景节点自动收集用 PERSIST 组 + save()/load()；模式演进用迁移管理器；防篡改用加密 FileAccess。
22. 不要在本技能中粘贴 Step 1–3 的 JSON Autoload 教程，直接按脚本实现。
23. 按需渐进加载：只在研究具体 API 时打开官方文档链接，只在路由到相邻领域时加载相关技能，不要预载整个技能网络。

适用边界 · 注意事项

• 不适用于非 Godot 引擎项目（本技能依赖 user://、FileAccess、PERSIST 组等 Godot 专有机制）。
• 不适用于需要服务器权威状态同步的多人竞技场景，此时应改用服务端校验与快照格式，而非明文 user:// 存档。
• 不适用于纯设置项持久化，设置应单独用 ConfigFile 处理，不必套用完整存档/迁移流程。