# 云端版本与本地缓存

> 谁是权威版本、编辑怎么落盘、图片如何上云，以及未登录时剩下的能力。

Source: https://loomworld.cn/docs/sync-model

## 谁是权威版本，谁是缓存

普通免费账号的项目保存在本机，登录不会自动上传。有效订阅或已登记的 Global 历史权益允许为选定项目开启同步；开启后云端保存账号内的版本，设备保留完整本地副本。Web 使用当前浏览器的 IndexedDB，桌面端使用本地项目文件夹与 SQLite 库。

打开一个已链接项目时按这个顺序判断：

- 先用项目列表里的摘要比对版本：云端没变、本地也没有待上传内容，就跳过整包拉取，直接开写。
- 云端有更新而本地干净（没有任何待上传修改）时，拉最新稿覆盖本地缓存；桌面端随后回写设计文件与派生档案。
- 本地有待上传内容（包括那 350 毫秒防抖里还没落盘的编辑）且云端也有新版时，进入冲突，两边都留。

## 保存与上传的次序

每一次编辑先保存到本地。项目已开启同步且账号具有有效云端权益时，保存成功后才排进上传队列。网络失败不会撤销本机修改；有效权限下恢复连接会重试，上传期间继续写作也会保留最新稿。订阅到期或权益查询失败只暂停上传，本地写作继续。

- 顶栏区分「本机已保存」与「已同步」，也显示同步中、离线、暂停、失败和冲突。云失败不改变本地保存成功这一事实。
- 打开的已链接项目会在窗口重新聚焦和每 60 秒各做一次摘要心跳；后台标签不跑定时，切走或关掉项目就停。心跳不会在你还打字时悄悄换稿。
- 发起云端 AI 任务前，客户端会先排空同步队列并校验版本一致；对不上时明确阻断，而不是拿旧数据继续跑。

## 图片怎么上云

上行时会先把正文与资料里的长 data URL 图片拆成内容寻址数据：同一项目内的相同图片复用同一份资产，项目 JSON 里只留轻量引用；打开与对账时再按引用把图片还原回本地。首次上云也走同一条路径——图没传完会把刚建的云端项目丢进回收站、本地不建链接，不留半成品。

- 拉不到的图片引用会原样留在稿里并标同步错误，不会被悄悄删掉。
- 单张图超过 20 MB 原始字节、或拆完图之后正文仍超过 32 MB，会标错误态且相同内容不再反复重传。这种项目请拆分或压缩图片后再传。

## 未登录与离线时

未登录或普通免费账号的本地项目不自动上传。浏览器作品依赖当前浏览器的数据存储，清除网站数据会删除仅在本机的项目与未上传修改；换浏览器或设备请先导出项目包。桌面端使用本地项目文件夹，可以自行拷贝备份。

离线时可以继续本地写作，云同步权限有效时联网后补传。订阅到期不删除已有作品，本机仍可编辑、保存和导出，已有云端项目仍可读取、导出或删除；续购后先核对双方版本再恢复同步。云端项目被删除时，本地链接会拆除，本机作品保留。

## 限制与排错

- 同步是内容级的整包对账，不做字段级三方合并——所以冲突的处理方式是「两边都留」，不是自动合稿。
- 遇到同步错误先保留当前页面与本地项目，不要清网站数据；重复出现的失败会在顶栏保持「同步失败」并带原因。
- 换设备的第一步是导出 .quill.json 项目包，而不是复制浏览器缓存。

冲突之后怎么找回内容见 [冲突副本](https://loomworld.cn/docs/conflict-copies)，备份与迁移见 [导出与导入项目包](https://loomworld.cn/docs/export-quill)。