该技能用于在浏览器游戏中实现可靠的存档与读档,目标技术栈为浏览器客户端、Bun 服务端、通过 Drizzle 0.45 访问的 Postgres 以及 Redis。数据库的建表与迁移沿用 postgres-game-schema,本技能只补充存档表与存档规则。
用途
它解决的核心问题是:游戏进度该保存在哪里、以什么格式保存、什么时候保存、写入失败或多设备同时写入时如何不丢进度。技能按用途把状态分成三类:其他玩家或商店在意的数值(货币、物品、排位进度)写入服务端的规范化数据表,由服务端逻辑决定和存储,客户端只上传输入;玩家不愿丢失的单人进度保存在服务端存档槽,同时保留本地副本,服务端副本还可跨设备漫游;设置、按键绑定、未登录的游客会话只存浏览器,丢失代价小。
主要能力
-
存储位置决策:明确服务端存档槽不保存服务端无需信任的状态,上传的存档中不接受货币、物品或奖励,这些由服务端自行计算;Redis 不作为存档记录,durable 进度写 Postgres,Redis 只保存实时会话状态;服务端存档的玩家 ID 来自会话,不来自请求体;客户端混淆或签名存档不能替代这套设计,离线单机游戏应接受本地存档可被编辑。
-
浏览器存储规则:使用 IndexedDB 而非 localStorage,后者同步阻塞主线程、只存字符串、每源约 5 MiB 上限且 worker 中不可用。浏览器存储是尽力而为的,存储压力下会按最近最少使用清除整个源的数据,同源的备份槽会一起消失;Safari 在开启跨站跟踪防护时,若七天内有浏览而无点击,会删除脚本写入的存储。技能建议在首次保存的点击处理中调用 navigator.storage.persist(),并处理 QuotaExceededError、localStorage 的 SecurityError,以及隐私模式下数据不持久的问题;IndexedDB 的结构变更只在 onupgradeneeded 中发生,需处理 onblocked 与 onversionchange。
-
存档格式:每个存档是一个信封,包含 format、version、savedAt、playedMs、sha256 以及以 JSON 字符串表示的 payload。写入时总是写当前版本;升级是单向的;设有 minLoadable 作为可迁移的最旧版本窗口;迁移按 n 到 n+1 一步一个函数,已发布的步骤不可修改只能新增;迁移后按当前结构校验,写入前也校验;键名像 protobuf 字段号一样不复用语义;只存纯数据,把向量、颜色、Map、Set、Date、BigInt 等转换掉;程序化内容存种子加玩家改动,并在种子旁存生成器版本;存档与读档必须可往返,测试 load(save(state)) 等于 state。
-
原子写入:浏览器每次保存使用一个 IndexedDB readwrite 事务,writeSlot 在同一事务中把当前存档移到 <slot>:backup 再写新存档,并用本地修订号检测过期标签页,返回 stale 而不写入;服务端每次保存使用一个 Postgres 事务,需支持交互式事务的驱动(Drizzle 0.45 的 neon-http 驱动会在 db.transaction 上抛错),saveToSlot 使用 SELECT ... FOR UPDATE 锁行,把旧版本复制进 save_slot_history、更新槽位并清理旧历史;文件场景先写临时文件再重命名覆盖,不假设 Bun.write 是原子的;同一玩家同一槽位一次只允许一个保存操作,从一致的游戏状态快照序列化。
-
槽位与备份:提供命名槽位加一个自动存档槽,自动存档绝不覆盖手动槽;保留每个槽位的上一版本,服务端保留最近 KEEP_HISTORY 行历史(默认 5);加载失败时尝试备份并告知玩家恢复了哪个存档,恢复后的下一次写入传入 keepBackup;迁移前的副本保留到迁移后存档加载并校验通过;从历史恢复也走同一修订检查与事务,先运行 migrateAndValidate,无法加载则拒绝且不改动槽位;数据库本身按托管方说明备份,槽位历史防坏档不防丢库。
-
保存时机:在检查点和定时器上保存是主路径;在 visibilitychange 变为 hidden 时也保存,因为移动端关闭标签页不会触发 unload;仅在存在未保存更改时挂 beforeunload,保存后移除;加载时检查 document.wasDiscarded,页面可能已被浏览器丢弃内存。
-
跨设备冲突:不用最后写入获胜,而是用修订号检查:客户端加载槽位并记下修订号,保存时携带该修订号(类似 HTTP 的 If-Match 与 ETag),saveToSlot 仅在存储修订号仍匹配时更新,否则返回 conflict 与元数据,以 409 或 412 响应;冲突时并列展示两个存档的保存时间与游玩时长让玩家选择,绝不静默代选;游客本地进度登录到已有服务端进度的账号时同样不自动覆盖。
-
损坏与平台规则:loadSave 在解析前对精确 payload 字符串做 SHA-256 摘要检查(crypto.subtle.digest,仅安全上下文),不匹配则回退备份;该摘要只防意外,不是防篡改;服务端行无需摘要。技能还列出 Steam Auto-Cloud 与 Xbox XR-052 的存档要求,并说明云存档必须可被玩家关闭而保存仍需可用。
使用方式
按步骤执行:先把每项状态按“存档放在哪里”归类并移除存档载荷中的有价值状态;复制 boilerplate/save-envelope.ts 定义存档类型、校验器、current=1、minLoadable=1;浏览器场景复制 boilerplate/browser-save-store.ts,首次手动保存调用 requestPersistence,接入 autosaveOnHide,捕获 QuotaExceededError;服务端场景复制 boilerplate/server-save.ts,在 schema 中加入 save_slots 与 save_slot_history 并以 player_id 外键关联 players.id,用 drizzle-kit 生成迁移,保存路由从会话取玩家 ID、限制请求体大小、对上传信封调用 loadSave、用迁移后数据与 formatVersion=spec.current 调 saveToSlot、冲突返回 409,加载路由调 loadSlot 再 migrateAndValidate;跨设备存档上线前先做冲突界面;加入往返测试与覆盖 minLoadable 起每个版本存档样本的测试;每次修改存档类型都要升 current、加迁移步骤、加样本。
适用场景
适合需要可靠存档的浏览器游戏,尤其是含服务端权威状态、需要跨设备续玩、需要版本迁移与备份恢复的项目。
限制
资料未提供该技能的收费、授权、支持平台数量等信息;其内容依赖指定的 Bun、Postgres、Drizzle 0.45、Redis 栈;平台云存档规则只在对应平台发行时适用。