做 Godot 项目做久了你会发现“存档”是所有游戏绕不过去的一道坎。不管是玩家进度、角色属性、背包物品还是音量分辨率你总得找个地方把数据记下来。网上关于 Godot 存档的教程不算少但多数只教一种写法要么贴一段代码让你照抄根本没说清什么时候该用 Config什么时候该上 JSON什么时候值得自己写二进制格式。这篇就是来补这个空的。我会从需求分类讲起把 Config、JSON、自定义三种方案做一次完整对比再给每套方案写可以直接抄进项目的 GDScript 代码最后把我踩过的坑、存档版本迁移、文件损坏恢复这些事一起说清楚。刚接触 Godot 4 的新手可以把这篇当作存档入门参考已经会写基础逻辑但正纠结选型的开发者也能在方案对比和避坑部分找到你要的东西。1. 选型之前先做需求分类你的存档属于哪一类看过的求助帖越多越觉得很多人不是不会写存档而是没想过自己到底需要哪种存档。需求不确定方案自然没法选。1.1 先回答三个问题存什么、多久存一次、谁要读第一个问题是“存什么”。你只需要存几个设置项比如分辨率、音量、语言还是需要存一个包含玩家坐标、血量、物品栏、任务进度、NPC 状态的复杂结构这两种需求对格式的要求完全不同。第二个问题是“多久存一次”。是一进入游戏读一次、退出前写一次还是每次玩家切场景、拾取物品、打开宝箱都要写入写入频率越高越要考虑文件体积和读写耗时否则玩家会明显感觉到卡顿。第三个问题是“谁要读”。这里说的“谁”包括机器和你自己。你的游戏代码要读这是最基本的。但如果以后你想写一个存档查看器或者玩家希望手动修改配置文件那存档格式最好是可读的文本格式如果存档只是给程序自己用二进制格式反而更省空间。把这三个问题的答案写在纸面上选型其实已经完成一大半。1.2 自带方案的优势与边界Godot 提供的存档手段很直白ConfigFile 适合做键值对配置JSON 适合做结构化数据FileAccess 配合自定义格式则能处理高性能和大体量场景。很多刚接触引擎的开发者容易犯一个误区觉得自定义格式显得“专业”一上来就用二进制结果存取逻辑写了一堆最后发现需求只是多存几个设置项维护成本白白抬高了。反过来也有另一种极端所有数据不分青紅皂白全塞 JSON哪怕只是一张地图上几千个敌人的位置每次自动存档都要序列化整个字典存档文件越来越大加载越来越慢。这不是 JSON 的问题而是需求分类没做好。我自己习惯先画一张表把项目里的数据项逐条列进去字段名、类型、写入频率、是否需要玩家可读、是否敏感。表画完三种方案各自对应哪些行就已经一目了然了。2. Config、JSON、自定义三套方案的取舍逻辑明确了需求再来看三套方案背后的设计逻辑。理解它们为什么存在你才不会用错。2.1 ConfigFile为“人类可读的键值配置”而生ConfigFile 在 Godot 里的本质是一个 INI 风格的文本文件由“节section”和“键key”组成。打开文件你就能直接看到[display] resolution1920x1080 fullscreentrue [audio] master_volume0.8这种格式的好处非常明显玩家可以打开存档文件直接改配置你调试的时候也能一眼看出数据有没有写对不用经过任何转换。它的缺点也很明显表达复杂嵌套结构非常别扭。举例来说如果你想存一个物品栏里面每个物品有 id、数量、耐久度用 ConfigFile 写出来的效果大概是[items]下一堆item_0_id、item_0_count、item_0_durability之类的键。读取的时候还要写循环去拼这些键名既啰嗦又容易出错。所以我的结论是ConfigFile 最适合“全局设置类”数据比如音量、画质、键位、语言。它不是给你存复杂进度用的。2.2 JSON表达复杂结构代价是可读性下降JSON 是文本格式里表达复杂结构最自然的选择。字典嵌套数组、数组嵌套字典一套写下来结构非常清晰。Godot 4 对 JSON 的支持也做得不错序列化和反序列化各一个方法就能完成。JSON 比 ConfigFile 更灵活但有两个需要注意的地方。第一个是文件体积会偏大因为每个键名、每个括号都要占字节第二个是解析后得到的都是基础类型JSON 里没有 Vector2、Vector3、Color 这些 Godot 内部类型你需要自己把坐标、颜色转成数组存进去读取时再转回来。这套“存取时手动转换”的功夫省不了但比 ConfigFile 硬拼键名要容易维护得多。2.3 自定义格式用复杂度换体积和速度当你存的数据不是给人看的而是希望在尽量小的体积、尽量快的速度下被程序读回去就该考虑自定义二进制格式了。用 FileAccess 把数字按固定字节数写进文件读出来的时候按相同规则解析整个过程没有任何字符串格式化的开销。但这种方案的前期成本很高你必须自己设计布局前几个字节存什么每个字段多大怎么处理版本差异文件损坏了怎么判断。而且一旦设计失误后面改格式的代价远比 JSON 大。2.4 快速选型对照表判断维度ConfigFileJSON自定义二进制数据结构复杂度低适合键值中高适合嵌套任意但需要自设计文件可读性很好较好几乎不可读读写性能一般一般最好文件体积偏大偏大最小调试便利性很好好差需要工具辅助版本迁移成本低中高典型用途设置项、轻量进度玩家存档、任务状态大数据量、频繁自动存档看到这张表你应该能理解为什么大多数中小型游戏项目最终都会选 JSON它处在“表达能力和维护成本”的最佳平衡点。Config 管设置JSON 管进度自定义留给真正需要它的场景。3. ConfigFile 实战从设置到轻量进度的完整写法3.1 保存设置项基础写法与你容易忽略的检查先来一套最常规的写法。假设你要保存音量、全屏开关和窗口分辨率const SETTINGS_PATH : user://settings.cfg func save_settings(resolution: Vector2i, volume: float, fullscreen: bool) - Error: var cfg : ConfigFile.new() cfg.set_value(display, resolution, resolution) cfg.set_value(audio, master_volume, volume) cfg.set_value(audio, fullscreen, fullscreen) return cfg.save(SETTINGS_PATH)这里的set_value有三个参数节名、键名、值。节名可以用来区分不同模块避免所有键堆在一起。cfg.save()返回一个 Error 枚举值很多教程会忽略这个返回值但项目上线后你很可能遇到磁盘满、权限不足等情况不检查返回值存档写失败了你都不知道。读取的写法是对称的func load_settings() - Dictionary: var cfg : ConfigFile.new() var err : cfg.load(SETTINGS_PATH) if err ! OK: push_warning(配置文件不存在或读取失败使用默认设置) return { resolution: Vector2i(1280, 720), volume: 0.8, fullscreen: false } var result : {} result[resolution] cfg.get_value(display, resolution, Vector2i(1280, 720)) result[volume] cfg.get_value(audio, master_volume, 0.8) result[fullscreen] cfg.get_value(audio, fullscreen, false) return resultget_value的第三个参数是默认值。当键不存在或者类型对不上时直接返回默认值这比先判断键是否存在再取值要省事得多。3.2 我用 ConfigFile 踩过的类型坑ConfigFile 表面上存的是 “Variant”但写进文件时会经过文本化处理。整数、浮点数、字符串、布尔值这类基础类型是最稳妥的。复合类型就要小心了我早期试过直接存 Vector2cfg.set_value(player, position, Vector2(100, 200))当时确实把内容存进去了读出来的结果也正常。但后来升级 Godot 小版本发现同一份存档在旧版本写、新版本读Vector2 被当成了一个包含两个元素的浮点数组代码里直接当 Vector2 用就出错了。这种问题非常隐蔽不仔细打印类型根本看不出来。所以我的建议是用 ConfigFile 时复合类型一律拆成基础值去存。坐标就拆成pos_x、pos_y颜色就拆成r、g、b。虽然写起来繁琐但换来的是长期的稳定。如果你存的是一个字典或者数组ConfigFile 在 Godot 4 里其实可以保留结构但读取时返回的可能是Dictionary或Array而不是深层类型完全还原的副本。与其依赖这种不确定行为不如遇到复杂结构直接用 JSON。4. JSON 实操复杂存档结构与版本迁移4.1 一个可以直接抄的 JSON 保存模板先给一套通用模板。这段代码会把你游戏里的存档数据统一序列化写入user://save.jsonconst SAVE_PATH : user://save.json const SAVE_VERSION : 1 func save_game(player_data: Dictionary, world_data: Dictionary, items: Array) - Error: var payload : { version: SAVE_VERSION, player: player_data, world: world_data, items: items, saved_at: Time.get_datetime_string_from_system() } var json_str : JSON.stringify(payload, \t) var file : FileAccess.open(SAVE_PATH, FileAccess.WRITE) if file null: return FileAccess.get_open_error() file.store_string(json_str) file.close() return OK要点有三个。第一JSON.stringify的第二个参数传\t这样生成的 JSON 文件每个层级都会缩进用文本编辑器打开能直接阅读。如果存档体积很大、追求性能可以去掉这个参数文件会更紧凑。第二存档里一定要放version字段。随着开发进行你的存档结构一定会变版本号是以后做迁移逻辑的唯一依据。没有版本号的存档升级到一半基本等于作废。第三Time.get_datetime_string_from_system()这类时间信息虽然不影响游戏逻辑但调试时非常好用玩家反馈存档丢失时你能从文件末尾看到最后一次保存时间。4.2 加载 JSON 与强类型恢复读取端这样写func load_game() - Dictionary: var file : FileAccess.open(SAVE_PATH, FileAccess.READ) if file null: return {} var json : JSON.new() var err : json.parse(file.get_as_text()) file.close() if err ! OK: push_error(存档解析失败%s第%d行 % [json.get_error_message(), json.get_error_line()]) return {} if not json.data is Dictionary: push_error(存档根节点不是字典拒绝加载) return {} return json.data这里必须强调一点JSON.parse返回的是一个 Variant 数据虽然你写的时候是 Dictionary但一定要做类型检查。我见过不止一次因为存档文件被外界改坏解析出的结果变成了字符串或数组代码往下直接按字典取键名立刻崩溃。JSON 里没有 Godot 自带的向量类型所以你的存档数据在放进字典前要手动转换。举个例子func save_position(pos: Vector3) - Array: return [pos.x, pos.y, pos.z] func load_position(data: Array) - Vector3: return Vector3(data[0], data[1], data[2])这类小函数建议封装在一个独立的存档工具类里永远不要在业务逻辑里直接写裸的数组下标转换否则后期维护你会想骂人。4.3 版本迁移升级存档结构的标准流程开发过程中最常遇到的痛点是你已经在游戏里加了新的武器系统但玩家手里的存档还是旧结构没有对应字段。最直接的报错方式就是读取时访问不存在的键。标准做法是写一个迁移函数。假设旧版本是version1新版本version2func migrate_data(data: Dictionary) - Dictionary: var version: int data.get(version, 0) if version 2: # 旧版本没有武器列表补一个默认空列表 if not data.has(weapons): data[weapons] [] data[version] 2 return data读档流程变成先解析原始数据再调用迁移函数最后才交给游戏逻辑使用。每次调整数据结构时只需要在迁移函数里追加一段if version N的分支保证旧版本存档能逐级升上来。我强烈建议迁移函数里的每个分支都写清楚注释说明这次迁移是补了哪个字段、为什么补。项目做了半年以后你不可能记得每个字段的来历。4.4 JSON 文件放到编辑器里预览的小技巧调试 JSON 存档最好在 Godot 编辑器里直接打开真实路径。在任意脚本里运行print(ProjectSettings.globalize_path(user://))这行代码会输出当前平台user://对应的真实目录。在 Windows 上通常是%APPDATA%\Godot\app_userdata\你的项目名在 Linux 上是~/.local/share/godot/app_userdata/...。配合编辑器的文件系统面板或者在系统文件管理器里打开这个目录你可以随时检查存档文件的实际内容排查问题能快很多。5. 自定义二进制实操体积、压缩与防篡改思路5.1 什么时候值得自己写二进制格式如果游戏里有一张很大的地图需要记录成千上万个可破坏物、敌人刷新点每次自动存档都序列化成一个巨大的 JSON 数组文件轻松涨到十几甚至几十 MB加载时还要把整段大文本解析成对象那种卡顿你在开发机上可能感受不明显玩家机器上就会很明显。这种场景才值得上自定义二进制格式。你按固定字节数写数字每个敌人只占几百字节寺节点和括号全部消失文件体积能压到 JSON 的十分之一。同时二进制读写速度极快没有字符串解析过程适合频繁自动存档。代价也摆在明面文件不可读出问题难排查格式一旦定下升级要格外小心因为你不再有“缺个键就补默认值”的容错读错一个字节后面的所有字段都会错位。5.2 带版本字段的二进制存档模板先给一个最简单的模板const SAVE_PATH : user://save.bin const SAVE_VERSION : 1 func save_binary(best_score: int, player_name: String, position: Vector2) - Error: var file : FileAccess.open(SAVE_PATH, FileAccess.WRITE) if file null: return FileAccess.get_open_error() file.store_32(SAVE_VERSION) file.store_32(best_score) file.store_pascal_string(player_name) file.store_float(position.x) file.store_float(position.y) file.close() return OK func load_binary() - Dictionary: if not FileAccess.file_exists(SAVE_PATH): return {} var file : FileAccess.open(SAVE_PATH, FileAccess.READ) if file null: return {} var version: int file.get_32() if version ! SAVE_VERSION: push_error(存档版本 %d 与当前版本 %d 不一致 % [version, SAVE_VERSION]) file.close() return {} var result : { best_score: file.get_32(), player_name: file.get_pascal_string(), position: Vector2(file.get_float(), file.get_float()) } file.close() return resultstore_pascal_string很有意思它会先写一个长度字节再写字符串内容。读取时用对应的get_pascal_string引擎自动知道要读多长的字符串省得你自己处理长度分配。这是最简单的手工布局。如果你有大量同构数据比如怪物列表可以在一个固定区域里循环写入for monster in monsters: file.store_16(monster.type_id) file.store_float(monster.position.x) file.store_float(monster.position.y) file.store_8(monster.hp)每个怪物固定 8 个字节加载时你甚至可以根据文件大小直接算出有多少个怪物不需要额外存数量。这种紧凑度是 JSON 完全做不到的。5.3 使用 store_var 的便利与陷阱Godot 的 FileAccess 还提供了一个更省事的接口store_var和get_var。你可以直接存一个字典进去引擎自动处理类型信息file.store_var(player_data_dict)读取var data: Variant file.get_var()听着很完美对吧但有两个重要警告。第一存入的字典里的Vector3、Color等类型可以直接保留比 JSON 方便得多。但如果你的字典里包含某个对象实例比如不小心把某个 Node 引用存进去了那么读取时引擎需要重新构造一个对象这往往不是你想要的还可能因为脚本未加载而报错。所以我的建议是存储内容只放纯数据绝不放节点引用或资源对象。如果你的数据结构里包含这些用full_objectsfalse的默认参数也救不了你。第二store_var的格式是引擎内部的序列化格式不保证跨大版本兼容。你年初用一个 Godot 4.2 版本存的文件到了年中升级到 Godot 4.4有可能读不出来或格式有微妙变化。所以即使使用store_var也一定要在文件开头单独写一个可读明文标记和版本号确认版本后才继续读取。5.4 压缩与防篡改的真实经验二进制方案经常伴随着压缩需求。Godot 4 自带了ZIPReader和ZIPWriter可以把多个存档文件打包压缩或者对单个大文件做压缩后写入。不过我的建议是如果你只是想把一个大 JSON 压小一点先别急着设计一套自有压缩格式。先用 JSON 自带的紧凑模式序列化再包一层压缩很多时候体积就已经降下来了。只有当你连序列化到字符串的时间都嫌长才需要考虑直接写二进制。防篡改是一个经常被误会的点。你可以在存档末尾写一个校验和比如对前面所有字节做一次循环冗余校验加载时重新算一遍。这能防止文件被传输出错、或者玩家手动改文件后加载报错。但它是防“误改”和“损坏”不是防“作弊”。真正想做反作弊必须在服务器端校验关键数值本地任何加密手段都只能提高修改门槛做不到绝对安全。如果你只是做一个单机游戏我的建议是不要在加密上花太多时间玩家改存档是社区生态的一部分有时候反而能延长游戏寿命。6. 常见存档问题的排查与恢复技巧无论你选哪种格式总会遇到同样的毛病。这一节挑几个我实际踩过的坑说说希望能让你少走弯路。6.1 user:// 路径到底在哪里很多新手第一次打开线上日志看到报错里的user://会很蒙。这不是项目目录里的某个文件夹而是引擎根据操作系统自动分配的“用户数据目录”。它在每个平台上的位置都不同Windows 上通常在%APPDATA%macOS 在~/Library/Application Support/GodotLinux 则在~/.local/share/godot。你在项目设置里选择的游戏名称会作为子目录出现在其中。把这个路径当作一个抽象的、跨平台的可写区域就好。永远不要硬编码绝对路径否则换个机器存档就会丢失。6.2 读档时最容易崩的一句话没有做解析结果检查就强制类型断言是最常见的崩溃点。JSON 解析出来的json.data可能是Dictionary也可能是Array、String、float甚至null。遇到被玩家手动改坏的存档文件、或编辑器里残留的旧模板文件解析结果很容易不符合你的预期。所以加载函数的开头一定要对根节点的 type 做防御性判断然后对每个关键子字段都使用data.get(key, 默认值)的形式而不是直接data[key]。这样即使缺失字段也不会直接崩溃顶多回落到默认值。6.3 文件写一半断电导致存档损坏游戏崩溃或断电时存档文件可能只写入了一半。下次启动读档解析就会报错。我现在的做法是先写一个临时文件确认写成功后再覆盖正式文件。const TMP_PATH : SAVE_PATH .tmp func save_game_safely(payload: Dictionary) - Error: var json_str : JSON.stringify(payload, \t) var file : FileAccess.open(TMP_PATH, FileAccess.WRITE) if file null: return FileAccess.get_open_error() file.store_string(json_str) file.close() # 先移除旧文件再重命名临时文件 if FileAccess.file_exists(SAVE_PATH): DirAccess.remove_absolute(SAVE_PATH) var err : DirAccess.rename_absolute(TMP_PATH, SAVE_PATH) return err这样一来“写半个文件”只可能发生在临时文件上正式存档要么是完整的旧版本要么是全新的完整版本不会出现中间状态。这个思路在 PC、主机平台都适用成本又很低强烈建议加入到你的存档管理里。6.4 关闭游戏时保存但节点已经没了我踩过的一个经典坑是在NOTIFICATION_WM_CLOSE_REQUEST里访问场景中的节点属性结果某些节点已经被释放一取属性就报错。如果你要做一个“退出前自动保存”的功能尽量把保存逻辑放在单例Autoload节点里并且在一进入退出流程时立刻保存不要依赖具体场景节点的存在。更保险的做法是把“自动保存”分散到关键节点变化时比如玩家拾取物品、完成任务、进入新区域时就写存档而不是只把希望寄托在退出时的最后一次写入。7. 选型到落地我的固定做法与额外建议最后再分享一点我的个人习惯。现在接到新项目我第一反应已经不再是追求某种酷炫格式而是先列需求。纯设置项直接 Config复杂进度和玩家状态统一 JSON只有数据量大到影响性能才上自定义二进制。版本字段永远是第一个写的数据迁移逻辑永远和读档逻辑绑在一起这让我后面改结构时不用再对着旧存档猜半天。存档本质上是一个数据接口你要保护的并不是某个格式本身而是当需求变化后你的玩家数据还能不能平滑地升级到新版本。把版本管理和容错做好比纠结用哪种格式重要得多。希望这篇能帮你少踩几个我踩过的坑。