UE5.8 存档与持久化：一次把 SaveGame、版本兼容与云同步讲透

引子：上线前夜，存档崩了

上线前三天，老周盯着屏幕上的一条崩溃栈，手心发凉。他的独立游戏《深渊旅人》已经跑完三轮 QA，偏偏在最后一次完整流程测试里，读取第三章存档时引擎直接闪退。那是一份用了三个月的本地 JSON 档，里面塞着角色等级、背包、任务进度、音量和画面设置。备份没有。玩家测试群里已经有人在问：三小时进度还能找回来吗？

问题很快定位。两周前老周给武器加了耐久度字段，策划要求旧档也能继续用。他直接在 JSON 里插了一个 Durability，旧档没这个键，反序列化时用了默认值 0，后续一段计算把 0 当除数，存档逻辑连带游戏一起崩了。

这件事让老周意识到，持久化不是把数据写进文件就完事。真正要面对的是版本变化、格式校验、加载失败时的回退路径，以及玩家对进度丢失的零容忍。

UE5.8 的 SaveGame 系统把这些事拆成了清晰的模块。这篇文章从这次事故出发，把存档与持久化从头到尾讲一遍。

architecture-beta
    group game[游戏进程]
        service gi[UGameInstance]
        service sgm[SaveGameManager]
    end
    group engine[引擎持久化]
        service ug[UGameplayStatics]
        service sg[USaveGame]
    end
    group storage[存储层]
        service disk[本地 Slot 文件]
        service cloud[云存档后端]
    end
    gi:B --> T:sgm
    sgm:B --> T:ug
    ug:B --> T:sg
    sg:B --> T:disk
    sgm:B --> T:cloud

一、USaveGame 与 Slot：最省心的默认方案

UE 里所有存档对象的基类是 USaveGame。写一个自己的存档类，继承它，在里面用 UPROPERTY(SaveGame) 标记要存的字段，就能交给引擎处理序列化。最常用的一对函数是 UGameplayStatics::SaveGameToSlot 和 UGameplayStatics::LoadGameFromSlot。

Slot 这个名字容易让人误解。它不是数据库表，也不是 Steam 云存档里的某个容器，就是一个字符串标识。SaveGameToSlot(SaveObject, TEXT(Slot0), 0) 会把 SaveObject 序列化成二进制，写到平台的用户存档目录。UserIndex 在主机分玩家时才有意义，PC 上通常给 0。

存档文件的实际路径由平台决定。Windows 上一般在 %LOCALAPPDATA%\MyGame\Saved\SaveGames\Slot0.sav。主机和移动端会映射到各自的沙盒目录。对开发者来说，这个路径是透明的，除非你打算手动做备份或云同步。

下面是一份最小可用的 C++ 示例。

UCLASS()
class MYGAME_API UMySaveGame : public USaveGame
{
    GENERATED_BODY()
public:
    UPROPERTY(SaveGame)
    int32 SaveVersion = 1;

    UPROPERTY(SaveGame)
    FString CurrentLevelName;

    UPROPERTY(SaveGame)
    TArray<FInventoryItem> Backpack;
};

void UMyGameInstance::WriteSlot(const FString& SlotName)
{
    UMySaveGame* Save = Cast<UMySaveGame>(
        UGameplayStatics::CreateSaveGameObject(UMySaveGame::StaticClass()));
    Save->CurrentLevelName = GetWorld()->GetMapName();
    Save->Backpack = Backpack;

    const bool bOk = UGameplayStatics::SaveGameToSlot(Save, SlotName, 0);
    UE_LOG(LogSave, Log, TEXT("Save to %s: %d"), *SlotName, bOk);
}

void UMyGameInstance::ReadSlot(const FString& SlotName)
{
    if (UGameplayStatics::DoesSaveGameExist(SlotName, 0))
    {
        UMySaveGame* Save = Cast<UMySaveGame>(
            UGameplayStatics::LoadGameFromSlot(SlotName, 0));
        if (Save)
        {
            Backpack = Save->Backpack;
            CurrentLevelName = Save->CurrentLevelName;
        }
    }
}

SaveGameToSlot 返回布尔值，代表本次写盘是否成功。它不会帮你检查数据是否合理，也不会帮你做版本兼容。那些事情必须在上层完成。

多存档槽的设计靠不同 Slot 名字实现。Slot0、Slot1、AutoSave、Checkpoint_3_2 都是合法名字。建议把元数据单独存一份，比如 MetaSlot，用来记录每个槽的创建时间、游戏内时长、章节截图路径，方便选择界面展示。

Slot 名字里不要带中文或特殊符号，某些平台会对文件名做规范化处理，特殊字符可能导致 DoesSaveGameExist 返回不一致。建议用 ASCII 字母、数字和下划线组合。

二、SaveGame 属性标记：哪些字段该进档案

UPROPERTY(SaveGame) 是告诉引擎：这个字段在序列化 USaveGame 对象时要一起写进文件。没有标记的字段，即使类型再简单，也不会被默认的 SaveGame 归档捕获。

反射系统会遍历 USaveGame 子类的所有属性，把带 SaveGame 标记的字段收集起来，写入 FArchive。这个过程中，基础类型、结构体、容器都能被处理。像 AActor* 这种指向世界对象的指针不能直接用 SaveGame 标记保存，因为关卡切换后原对象可能已经被 GC。要保存的应该是足以重建状态的数据，比如 Transform、Actor 的持久化 ID、物品的 RowName。

老周在《深渊旅人》里保存玩家位置时，最初存了 AActor*。结果加载新关卡后指针悬空，角色被传送到 (0,0,0)。改成保存 FVector 和 FRotator 之后，问题消失。

graph TD
    Save[USaveGame 对象] -->|SaveGame 标记| P1[基础类型]
    Save --> P2[结构体]
    Save --> P3[容器]
    P3 --> P4[TArray]
    P3 --> P5[TMap]
    P3 --> P6[TSet]
    P1 --> Arc[归档写入]
    P2 --> Arc
    P4 --> Arc
    P5 --> Arc
    P6 --> Arc

标记属性时要注意粒度。把所有东西塞进一个大结构体看起来省事，但后续版本迁移会很痛苦。推荐的做法是按业务拆成多个子结构体：背包、任务、设置、成就、世界状态。每个子结构体独立版本号，迁移时可以局部处理。

另外，EditDefaultsOnly 或 Transient 标记的属性不会被 SaveGame 归档捕获。不要把运行时缓存、UI 状态、临时搜索路径这类数据塞进存档对象，它们会让版本迁移变得啰嗦，还白白占用磁盘。

持久化数据的体积大致和标记字段数量成正比。如果存档里包含 $n$ 个字段，平均每个字段占用 $s$ 字节，加上容器头部和字符串开销 $o$，整个存档大小可以粗略估计为：

$S \approx o + \sum_{i=1}^{n} s_i$

对于纯数值和短字符串的 RPG 存档，几十 KB 足够。如果保存了大量地图标记、截图缩略图或历史记录，体积会迅速膨胀到数 MB，这时要考虑分文件存储或压缩。

三、版本号与兼容性：旧档不能读死新程序

没有版本号的存档系统等于一颗定时炸弹。老周的事故就是典型例子：程序已经走到 1.1，存档还是 1.0 的格式，加载路径里没有任何兼容处理。

UE5.8 里最常见的做法是在 USaveGame 里放一个 SaveVersion 字段。每次修改存档结构时，把项目里的 CURRENT_SAVE_VERSION 常量加一。加载时比较存档里的版本号和当前支持的最低版本。

flowchart TD
    A[调用 LoadGameFromSlot] --> B{Slot 存在?}
    B -->|否| C[创建新存档]
    B -->|是| D[反序列化 USaveGame]
    D --> E{版本号检查}
    E -->|兼容| F[恢复游戏状态]
    E -->|过低| G[提示不兼容或删除旧档]
    E -->|可迁移| H[执行 MigrateFromOldVersion]
    H --> F

加载成功的前提可以写成一条简单的规则：

v_{\text{save}} \geq v_{\text{min}} \quad \text{且} \quad \text{结构校验通过}

如果 $v_{\text{save}}$ 小于 $v_{\text{min}}$，直接拒绝加载，并提示玩家需要重新开始。如果版本在支持范围内但字段有变化，就在 PostLoad 或专门的迁移函数里补默认值。

void UMySaveGame::PostLoad()
{
    Super::PostLoad();

    if (SaveVersion < CURRENT_SAVE_VERSION)
    {
        MigrateFromOldVersion(SaveVersion);
        SaveVersion = CURRENT_SAVE_VERSION;
    }
}

void UMySaveGame::MigrateFromOldVersion(int32 OldVersion)
{
    if (OldVersion < 2 && Backpack.Num() > 0)
    {
        for (FInventoryItem& Item : Backpack)
        {
            Item.Durability = Item.MaxDurability;
        }
    }
}

迁移代码要写得保守。不要假设旧档一定有某个字段，所有访问都要做判空或默认值处理。迁移完成后最好立即再存一次，把格式刷到最新，避免下次加载再走一遍迁移路径。

QA 阶段的旧档测试不能省。每次版本更新，都要准备一组从老版本生成的真实存档，验证迁移路径不会丢数据。这套存档集要覆盖空档、满级档、边界状态档，不能只测 happy path。准备一个最小化的回归脚本，能让这件事在每次构建后自动跑一遍。

四、二进制存档与 JSON 存档

SaveGameToSlot 默认走二进制序列化。它的好处是体积小、速度快、和 UE 的反射系统无缝衔接。坏处是人类读不了，调试时很难直接看出问题。

JSON 存档在开发期非常有用。策划和 QA 可以直接打开存档文件，检查背包里是不是真多了那把测试剑。实现方式是用 FJsonObjectConverter 把 USaveGame 转成 FJsonObject，再写到磁盘。

bool UMySaveGame::ExportToJson(const FString& Path)
{
    TSharedPtr<FJsonObject> Json =
        FJsonObjectConverter::UStructToJsonObject(StaticClass(), this);
    if (!Json.IsValid()) return false;

    FString Out;
    TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&Out);
    FJsonSerializer::Serialize(Json.ToSharedRef(), Writer);

    return FFileHelper::SaveStringToFile(Out, *Path);
}

JSON 输出还能直接交给版本控制做 diff，策划修改测试存档时一眼就能看出改了什么。缺点是解析速度比二进制慢，字符串字段多时体积也会翻倍。发版前务必将调试命令关闭，避免玩家拿到明文存档。

正式发布时建议用二进制。JSON 不适合直接给玩家，因为它体积大、解析慢、容易被修改。很多团队的做法是：开发期保留一个 Debug 命令，把当前二进制存档导出成 JSON；发版时只保留二进制路径。

二进制和 JSON 之间可以共享同一份 USaveGame 定义。区别只在最后的 FArchive 或 FJsonSerializer。这个分层做得干净，切换成本会很低。

二进制存档损坏时，可以临时把损坏文件复制出来，用编辑器里的调试工具对照 JSON 导出结果，定位是哪一块数据越界或被截断。

五、云存档：多端同步的冲突处理

老周后来把游戏上架到 Steam，又加了 Steam Deck 支持。他很快遇到另一个问题：玩家在家里的 PC 上玩到第三章，带着 Deck 出门，发现进度回到了第一章。云存档没有同步，或者更糟，旧档把新档覆盖了。

云存档的基本思路不复杂。本地有一个存档文件，云端也有一个副本。启动时拉取云端文件，比较时间戳和哈希值，决定用哪一份。真正的难点在冲突解决。

假设本地存档时间为 $t_l$，云端为 $t_s$；本地数据哈希为 $h_l$，云端为 $h_s$。冲突发生的条件是：

$(t_l \neq t_s) \land (h_l \neq h_s)$

如果只有时间戳不同但哈希相同，说明两边内容一致，只是写盘时间不同，直接跳过同步。如果时间戳和内容都不同，就必须做选择。

sequenceDiagram
    autonumber
    participant C as 客户端
    participant S as 云存档服务
    participant U as 玩家
    C->>S: 请求云端元数据
    S-->>C: 返回 t_s 与 h_s
    C->>C: 比较 t_l、h_l
    alt 完全一致
        C->>C: 无需同步
    else 云端更新
        C->>S: 下载并覆盖本地
    else 本地更新
        C->>S: 上传本地档
    else 冲突
        C-->>U: 弹窗询问
        U-->>C: 选择保留本地/云端/合并
        C->>S: 执行对应操作
    end

Epic Online Services 和 Steam 都提供了云存档 API，但策略细节不一样。Steam 默认是 last-write-wins，适合单人游戏。EOS 的 Player Data Storage 支持更灵活的元数据查询。如果做独立后端，可以用 S3 或 Azure Blob 存文件，再用一个元数据表记录版本、设备、时间戳。

哈希建议用 SHA-256 或更轻量的 xxHash，前者更安全，后者更快。云同步失败时要有重试上限，连续失败三次后进入离线模式，让玩家至少能继续本地游戏。

不管用哪家后端，都不要把云同步放在游戏关键时刻。应该在主菜单或关卡切换的加载屏里完成，避免玩家正在打 Boss 时弹同步窗口。上传也建议走异步，成功后更新本地元数据。

六、自动存档与检查点

玩家最讨厌的体验之一，是死了之后发现上一个手动存档在两小时之前。自动存档和检查点能把损失控制在可接受范围内。

检查点通常放在关卡关键位置：过完一段平台跳跃、击败一波敌人、进入新区域。触发器检测到玩家进入，就调用 SaveGameManager 写一份存档。自动存档则按时间或事件触发，比如每五分钟、切换装备后、完成一个支线。

UE5.8 中可以用 AsyncSaveGameToSlot 避免阻塞主线程。存档期间游戏继续跑，UI 显示一个小图标，写盘完成后再给玩家提示。

sequenceDiagram
    autonumber
    participant P as 玩家
    participant T as 检查点触发器
    participant M as SaveGameManager
    participant S as USaveGame
    participant U as UGameplayStatics
    participant D as 本地磁盘
    P->>T: 进入检查点区域
    T->>M: RequestCheckpoint
    M->>S: NewObject
    M->>S: 填充属性
    M->>U: AsyncSaveGameToSlot
    U->>D: 二进制写入
    D-->>U: 完成回调
    U-->>M: OnSaveFinished
    M-->>P: 显示提示

自动存档也要控制频率。太频繁会损坏 SSD，也可能在战斗中途写盘导致卡顿。推荐的做法是只在安全区触发，或者维护一个队列，等当前战斗状态结束后再执行。

UI 反馈不能少。玩家看到角落闪一下图标，就知道进度已经安全。如果写盘失败，要弹出明确提示，而不是悄悄丢掉这次检查点。

多检查点的管理上，可以保留最近 $n$ 个自动档，最老的被覆盖。这样玩家即使触发了一个坏档，还能回退到上一个自动档。

void ASaveTrigger::OnOverlap(AActor* Other)
{
    if (APlayerCharacter* PC = Cast<APlayerCharacter>(Other))
    {
        if (USaveGameManager* M = PC->GetSaveManager())
        {
            M->AsyncCheckpoint(TEXT("Auto"), this);
        }
    }
}

七、存档加密与防作弊

单机游戏是否需要加密存档，一直是个有争议的话题。对于纯单机体验，过度加密会增加维护成本；但如果游戏有排行榜、成就系统或内购货币，存档被修改就会直接影响其他玩家。

最基础的保护是给二进制存档加一道对称加密。写盘前先用 AES 加密字节流，读盘时再解密。密钥不要硬编码在源码里，可以从平台的安全存储或服务器获取。更进一步的做法是加 HMAC 校验，防止玩家篡改文件内容。

bool UMyGameInstance::SaveEncrypted(
    USaveGame* Data, const FString& Slot, const TArray<uint8>& Key)
{
    TArray<uint8> Bytes;
    FMemoryWriter Ar(Bytes);
    Data->Serialize(Ar);

    const TArray<uint8> Tag = HMAC_SHA256(Key, Bytes);
    AES256_Encrypt(Bytes, Key);

    return WriteSlotWithHeader(Slot, Bytes, Tag);
}

校验的逻辑可以写成：

\text{accept} \iff \text{HMAC}(K, B) = T

其中 $K$ 是密钥，$B$ 是存档字节，$T$ 是文件头里保存的校验值。校验失败时，可以当作损坏处理，回退到上一个可用存档或强制从头开始。

密钥管理是最容易被忽略的一环。不要把密钥字符串直接写在 Build 里，可以考虑在打包时注入，或者从授权服务器按需拉取。主机平台通常提供自己的加密容器，优先使用平台方案。

没有绝对安全的单机存档，但合理的加密和校验能把作弊成本提高到普通玩家不愿折腾的程度。

八、UE5.8 在持久化上的改进

UE5.8 对 SaveGame 系统的改动不算翻天覆地，但把几个长期痛点修得更顺手。

首先是异步写盘。AsyncSaveGameToSlot 在 5.8 里的回调更加稳定，委托参数里带上了明确的错误码，而不再是简单的成功或失败。开发期可以根据错误码决定是重试、降级还是弹提示。

其次是 Slot 枚举。旧版本想列出当前所有存档槽，需要自己扫描目录。UE5.8 在 UGameplayStatics 里补齐了相关辅助函数，返回该游戏已创建的 Slot 列表，方便做选择界面和云同步比对。

第三是二进制存档的压缩。5.8 默认对 SaveGame 字节流启用可选的 LZ4 压缩，对文本和重复数据较多的存档能显著减小体积。可以在 DefaultEngine.ini 里关闭：

[/Script/Engine.GameplayStatics]
bCompressSaveGames=False

最后是新加入的 FSaveGameValidator 概念。它是一个轻量钩子，允许项目在 USaveGame 加载完成后、应用到游戏状态前，执行自定义校验。比如检查数值是否越界、必要字段是否存在、哈希是否匹配。校验失败可以触发迁移或直接丢弃该档。

这些改进的方向很明确：让 SaveGame 从能用的工具，变成能在生产环境里放心交付的模块。

老周最满意的是可以直接在游戏内做一个存档浏览器，列出所有 Slot 的创建时间和大小，不用自己写文件扫描。这对 QA 和策划都是实打实的效率提升。

结语

老周最后把《深渊旅人》的持久化方案彻底重构了一遍。他用 USaveGame 替代了手写 JSON，给每个存档加了版本号和 HMAC 校验，做了三个手动槽、一个自动档、一组检查点，还在主菜单里接了 Steam 云同步。上线那天，他盯着 Steam 后台的崩溃曲线，终于松了口气。

存档系统不像画面和玩法那么显眼。但它一旦出错，玩家付出的时间成本无法挽回。花点时间把版本、校验、回退、加密、云同步这些环节做扎实，是对玩家最基本的尊重。

对独立团队来说，持久化方案不需要一开始就做得很重。先保证版本号和基本校验，再逐步加上自动档、云同步和加密，每一步都能降低未来的维护风险。

他也留了一条后路：每次大版本更新前，QA 会跑一遍旧档迁移测试，确保玩家升级后不会丢进度。这条流程写进了发布检查单，成了团队雷打不动的习惯。玩家进度保住了，睡得着觉的才不只是老周一个人。