Godot 云存档冲突处理：本地进度和云端进度不能只问玩家覆盖谁

云存档最怕一句是否覆盖

云存档冲突会直接伤害玩家信任，玩家在两台设备上都玩过以后，不能只弹一个覆盖谁的选择题。这个问题在项目早期经常被当成小功能，等内容量、平台数量和运营节奏上来之后才暴露成本。Godot 客户端要做的不是写一个临时脚本，而是把它当成可验证、可回滚、可观测的系统来设计。团队需要知道数据从哪里来，谁有权修改，失败后玩家看到什么。

给每份存档建立身份

存档要带 save_id、device_id、lineage_id、revision、content_version 和 checksum，不能只看更新时间。先把输入和输出数据结构定下来，字段要有版本、来源、时间戳和校验结果。不要让每个页面或节点自己拼数据。统一模型能让编辑器工具、运行时逻辑和 QA 脚本读取同一份真相，也方便后续接入平台差异。

冲突流程图

云存档处理可以分成检测、快进、合并、确认和备份几个阶段：

flowchart TD
    A["Local Save"] --> C["Conflict Detector"]
    B["Cloud Save"] --> C
    C --> D{"Compatible?"}
    D -- "same lineage" --> E["Fast Forward"]
    D -- "diverged" --> F["Merge Candidate"]
    F --> G{"Auto merge safe?"}
    G -- "yes" --> H["Apply merged save"]
    G -- "no" --> I["Player choice with details"]
    H --> J["Backup old saves"]
    I --> J

图里的每个节点都应该能单独记录耗时和失败原因。流程图不是文档装饰，而是帮助团队确认责任边界。某个阶段失败时，客户端应知道能否重试、能否降级、是否需要玩家确认。

哪些数据能自动合并

图鉴、设置、成就可以按安全规则合并，货币、背包、剧情选择必须保守。把规则写成配置或 Resource，而不是散在 UI 和业务脚本里。比如阈值、白名单、黑名单、平台差异、灰度条件，都应该能在不改核心逻辑的情况下调整。配置也要有默认值和校验，缺字段时使用保守策略。

给玩家看的差异要具体

冲突 UI 要显示设备、章节、等级、游玩时长、货币摘要和最后位置，让玩家识别进度。玩家看到的反馈要具体。只说失败没有意义，应该说明是资源不足、版本不兼容、网络不可用、数据已过期还是需要重新进入页面。Godot 的 UI 很容易弹一个 Toast，但真正关键的是 Toast 背后的错误码要稳定。

备份是底线

应用任何版本前都写入 backup slot，保留来源、时间和校验信息。对性能敏感的部分要做预算。不要把所有检查都放到同一帧，也不要在战斗或切场景高峰做大扫描。可以用分帧任务、后台准备和安全点提交。低端设备上，稳定比一次性完成更重要。

版本迁移和云同步顺序

下载云端到 staging，完成校验和迁移后再参与冲突判断。调试工具至少要显示当前状态、最近一次输入、最近一次输出、错误码、耗时和关联资源路径。很多线上问题不是算法错，而是资源、配置、平台状态不一致。把这些信息画出来，排查时间会大幅缩短。

离线游玩策略

离线游玩会让 revision 分叉，恢复联网后先上传摘要再做判断。QA 场景要覆盖正常路径、异常路径、低帧率、断网、切后台、语言切换、平台差异和重复操作。只测一次成功是不够的。真正决定系统可靠性的，是失败后能否回到一个干净状态。

QA 场景

要模拟时钟错误、上传中断、下载损坏、迁移失败和玩家选错后恢复。上线后要有轻量指标，但不要上传无关隐私。记录聚合数量、失败阶段、资源版本、平台和耗时分布即可。通过这些数据，团队能知道问题是集中在某个平台、某个资源包，还是某个流程阶段。

落地建议

先做元数据、备份和危险数据保护，再考虑更细的自动合并。落地时先做最小闭环：数据模型、执行流程、失败反馈、调试面板和一组 QA 用例。等闭环稳定，再扩展更多场景。Godot 给了足够的运行时自由度，工程上要补上的就是边界和纪律。

冲突摘要怎么生成

冲突摘要最好来自存档内部的 SummaryBlock，而不是打开完整存档后临时解析。SummaryBlock 包含角色名、等级、章节、当前位置、游玩时长、金币数量、最近任务、缩略图路径和最后保存设备。每次保存时同步更新摘要。这样即使完整存档版本较旧，客户端也能先展示基本信息，避免冲突界面空白。

摘要字段要保持向后兼容。新版本增加字段可以，旧版本缺字段时显示未知，不应阻止玩家选择。缩略图也要可选，截图损坏时仍显示文字信息。冲突 UI 的目标是帮助玩家识别，而不是要求存档完美。

合并策略表

可以给每个存档域配置 merge_policy：settings 取最近修改，codex 取并集，achievement 取最大进度，map_fog 取并集，inventory 禁止自动合并，quest 禁止自动合并，mail 以服务器为准。合并器按域执行，任何高风险域分叉都会让整体进入人工确认。

这个表要和服务端、平台云策略对齐。如果服务端已经权威保存资产，本地云存档就不应该再合并资产字段。客户端只保存表现和离线进度时，合并范围可以更大。关键是写清楚每个域的所有权。

备份恢复入口

只有创建备份还不够，玩家或客服要能恢复。可以在设置页隐藏一个“存档恢复”入口，列出最近备份：来源、本地时间、设备、章节、等级。恢复前再次创建当前备份，防止二次误操作。恢复操作必须重启场景或回到主菜单后执行，避免运行中状态和存档替换冲突。

正式包可以把入口做得谨慎，不需要鼓励玩家频繁使用，但它必须存在。没有恢复入口的备份只对程序有用，对玩家没有用。

平台云接口的异常

平台云可能返回成功但文件还未同步到另一台设备，也可能因为容量、登录状态或权限失败。客户端要区分平台错误和存档冲突。平台不可用时，不应阻止本地游玩，但要提示云同步暂停。上传失败后保留 pending 状态，下次启动或回到主菜单再重试。

不要在战斗中弹云存档错误大窗。云同步可以延后处理，除非玩家正在退出或切设备。提示节奏要考虑玩家场景。

安全和作弊边界

单机游戏本地存档可被修改，云存档合并不能假设所有字段可信。如果排行榜、成就或内购资产依赖存档，服务端必须做校验。客户端冲突合并只保护体验，不应成为资产权威。检测到 checksum 不匹配或签名异常时，保守处理：备份、提示损坏、尽量恢复最近可信版本。

工程边界要写在代码之前

云存档冲突最怕“先能跑再说”。能跑的脚本往往把本地存档、云端存档、备份和摘要混在一个节点里，短期看起来省事，后期每个 bug 都要跨 UI、资源、网络和玩法一起查。开工前先写清楚边界：版本 lineage、迁移、合并策略和玩家确认分别由谁负责，谁只读数据，谁可以提交状态变化，谁只能播放表现。边界清楚以后，新增需求通常只是加一个策略或 profile，而不是改一串互相调用的节点。

在 Godot 里，这个边界可以通过 Resource、autoload 服务和场景节点组合表达。Resource 保存可调规则，autoload 提供跨场景的状态和队列，场景节点负责当前画面表现。不要把全局状态藏在某个 UI 控件或临时子节点里。只要场景一切换，这类状态就会丢，问题还很难复现。

失败恢复要比成功路径先评审

成功路径通常很顺：玩家点击、系统执行、界面刷新。真正决定质量的是失败路径。双设备离线、时钟错误、下载损坏、选错存档后恢复这些情况都不是边角料，而是实际测试和上线后最容易出现的问题。每个失败都要回答三个问题：当前状态是否还能继续，是否需要回滚，玩家需要知道什么。没有答案时，就不要把功能当作完成。

失败恢复还要避免二次伤害。比如恢复时又触发一次旧请求，清理时误删仍在使用的资源，回滚时把玩家新操作覆盖。可以给关键操作加 transaction id 或 version，恢复时只处理当前版本。旧回调、旧异步任务、旧动画事件到达时，如果版本不匹配就丢弃。这个小机制能挡住很多偶现问题。

性能预算不能等卡顿后再补

云存档冲突通常不是单次成本大，而是高频、叠加或峰值明显。预算要写成数字：每帧最多处理多少对象，每次扫描最多多少毫秒，本地队列最多多少条，缓存最多占多少空间，失败重试间隔如何退避。没有数字时，团队会凭感觉加功能，直到某个场景突然掉帧或磁盘暴涨。

预算也要有降级策略。低端设备、后台恢复、弱网、资源不完整时，系统应该知道哪些表现可以降低，哪些规则必须保持。表现层可以降，权威状态不能乱；调试信息可以少，关键错误不能吞；刷新频率可以降，玩家资产和输入边界不能省。预算不是单纯砍功能，而是把优先级提前讲清楚。

团队协作需要工具，而不是口头约定

云存档冲突经常跨程序、美术、策划、QA 和运营。只靠口头说“这个资源别这么配”“这个按钮别这样关”很快会失效。更可靠的是做小工具：编辑器检查、运行时调试面板、资源报告、状态导出、固定压测场景。工具不一定复杂，但必须让非程序也能看到问题所在。

例如检查器可以扫出缺字段、错误引用、超过预算的资源、不可回滚的状态；调试面板可以显示当前 profile、版本、队列、耗时、错误码；固定测试场景可以一键复现高峰。工具越早出现，团队越容易在内容制作阶段修问题，而不是等集成测试时集中爆炸。

上线验收清单

上线前至少检查这些项：正常路径是否稳定，失败路径是否可恢复，切场景和切后台是否安全，低帧率或弱网下是否有明确降级，日志是否能定位问题，玩家提示是否具体，配置缺失时是否保守，旧版本数据是否兼容，重复操作是否幂等，调试开关是否不会进入正式表现。这个清单看起来普通，但每一项都对应真实线上事故。

还要留一个回看机制。上线后一周看聚合指标和玩家反馈，确认失败率、耗时、回滚次数或异常状态是否在预期内。没有指标的功能，只能等玩家投诉。云存档冲突做得好，不是玩家会夸它，而是它在复杂场景里安静地工作，不把风险转嫁给玩家。

合并后的校验

自动合并完成后，不能直接把结果写成正式存档。先对合并结果跑一遍存档校验：背包容量是否超上限，任务阶段是否存在，地图 id 是否有效，角色等级和经验是否匹配，装备引用是否能找到，道具数量是否为负。校验失败时，不要尝试修到看似合理，而是放弃自动合并，进入人工选择或恢复备份。合并器的职责是保守地组合可信数据，不是猜玩家应该处于什么状态。

校验还要记录合并来源。未来玩家反馈进度异常时，日志里能看到哪些域来自本地，哪些域来自云端，哪些域取了并集。没有来源记录，合并问题很难复盘。

推荐的最小实现顺序

如果项目还没有云存档，不要第一版就做复杂合并。最小实现可以分四步。第一步，本地存档加入 metadata 和 SummaryBlock，保存时自动生成摘要。第二步，上传和下载都走 staging，并在应用前创建本地备份。第三步，只支持同 lineage 的快进同步，发现分叉时弹出带摘要的选择界面。第四步，再为设置、图鉴、地图探索这些安全域增加自动合并。这样每一步都能上线验证，不会把所有风险压到一个大版本。

同时要给 QA 准备一组可复制存档：本地新、云端新、双端分叉、版本过旧、摘要损坏、checksum 错误。云存档测试最怕依赖真实平台状态，样本存档能让问题稳定重现。

上线后的维护

云存档冲突处理上线后，要定期抽查恢复链路。每次版本更新后，拿旧版本存档、分叉存档和损坏摘要跑一遍恢复测试。客服也需要知道备份位置和 receipt 信息，否则玩家真的遇到丢档时，工程做了备份却没人会用。

团队交接说明

团队交接时要把存档域说明写清楚：哪些字段只属于本地，哪些字段由服务器权威，哪些字段允许云端快进，哪些字段永远不能自动合并。新同事接手时，如果只能靠读代码猜这些规则，迟早会在某次活动或版本迁移里改错。建议在仓库里保留一份 save-domain-policy.md，并让存档校验脚本读取同一份配置，文档和代码就不会越走越远。