KOReader跨设备同步：10分钟打通进度和批注的完整配置-编程实验室

KOReader跨设备同步：10分钟打通进度和批注的完整配置

【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader

周六晚上你在 Kindle 上读到第 180 页，顺手标了几处高亮。周日换到手机，打开同一本书，进度条还停在 30 页，批注也全没了——多设备读书的常见尴尬。KOReader 的跨设备同步功能就是为此设计的，它分两条线：进度走专用同步服务，批注和统计等数据走云存储目录。跟着下面这套流程走，10 分钟以内就能让两台设备自动对齐。

能做什么，不能做什么

先把边界划清楚，免得对功能有错误期待：

进度同步：阅读位置推到 KOReader 同步服务器（官方或自建），两台设备双向对齐，支持"每翻 N 页自动推送"。
云存储接入：内置 Dropbox、WebDAV、FTP 三种服务，可以浏览、上传、下载云端文件。
数据文件同步：统计、词汇本这类按文件存的数据，放到云端同一目录就能跨设备更新。
批注和书签：没有一键自动合并，需要你把书的数据目录放到云端同一文件夹，手动触发同步。
不同步书文件本身：每台设备要各自放一份完全相同的书（文件名、内容一致，否则系统认为不是同一本）。
界面设置不走同步：字号、主题这些每台设备独立配置。

边界清楚之后，缺的东西不多，下一页列个清单。

动手前准备

逐条打勾，齐了就开工：

两台设备都装好 KOReader（Kindle、Kobo、Android 手机、电脑都行），版本一致
在同步服务器注册了同一账号，两台设备都用它登录
Dropbox 开发者后台建了应用，拿到 Refresh Token 和APP_KEY:APP_SECRET字符串
想好了云端目录（比如/KOReader/sync）和本地目录，两端保持一致
两台设备都能上 WiFi（自动同步依赖网络，这点后面还会提）

凭证是新手最容易卡住的一步：Dropbox 的短期令牌只有 4 小时有效期，所以配置时填的是"刷新令牌 + 应用密钥"这对组合，软件会自动换新令牌。准备齐全后进入实操。

实操走查：以 Dropbox 为例

1. 添加云存储

打开主菜单，点"云存储"。列表左上角是加号，点它，在弹出的"添加新服务器"里选 Dropbox。

2. 填凭证并保存

弹出四项输入：名称（随便起，比如"我的网盘"）、Refresh Token 或长期令牌、APP_KEY:APP_SECRET、起始目录。粘贴后点保存。

预期结果：看到根目录的文件和文件夹列表。如果提示"无法获取服务器内容，请检查配置或网络连接"，九成是令牌填错，回去重抄一遍。

3. 指定同步目录

长按刚添加的服务器名，弹出操作框。点"同步设置"，会显示当前的远程和本地目录（初始都是"未设置"）。分别点"选择远程目录"（进云端挑文件夹，长按选中）和"选择本地目录"（在本地挑目录），两处都填上。

4. 手动触发一次同步

回到操作框点"立即同步"。它把云端文件的清单和本地逐个比对大小，只下载不一致的，全程有进度条。完成后弹提示"已下载 N 个文件"。之后每次想更新，点同一个按钮即可。

5. 顺手把进度也同步了

主菜单进"进度同步"，完成账号登录，勾上"自动保持文档同步"，再设"每翻多少页推送一次"（0 表示不按翻页推送，只在关书、挂起时推送）。之后开书、关书、设备休眠，进度都会自己上传。到这里，云存储和进度两条线都通了，接下来花 1 分钟看看背后的机制。

它是怎么同步的

数据同步用的是"三文件"比对：本地文件、刚下载的云端文件，加上上次上传后留存的缓存副本。只看本地和云端，分不清"我删掉了"还是"别人还没传"；拿缓存当参照物，两边删掉的条目就能被识别出来，合并后不会死灰复燃。上传还带 etag 校验（云端文件的指纹），期间别人改过就返回冲突状态，软件会自动重试。核心逻辑就 200 来行，集中在 Cloud:sync 里。

进度同步是另一套机制：客户端把"书的指纹 + 百分比位置 + 设备名"推给服务器，拉取时比较时间戳决定要不要回跳位置；推送失败会先进重试队列，网络恢复后自动补传，见 KOSync 主逻辑。

机制不复杂，但真出问题时还是那几处坑，按图索骥即可。