MDVIEWER / BLOG
MD文件阅读器的 Git 云同步：把本地 Markdown 放进自己的仓库
Markdown 文件很轻，重要内容却可能很重：项目方案、读书笔记、AI 对话整理、课程资料和长期维护的个人知识库，都可能从一个小文件开始。 只保存在手机里，使用起来很方便，但换设备、误删文件或需要回看旧版本时，风险也会跟着出现。MD文件阅读器提供了可选的 Git 云同步，让本地仓库可以同步到你指定的 Gitee、GitHub 或其他支持 HTTPS Git 的私有仓库。
MD文件阅读器的 Git 云同步：把本地 Markdown 放进自己的仓库
Markdown 文件很轻，重要内容却可能很重：项目方案、读书笔记、AI 对话整理、课程资料和长期维护的个人知识库，都可能从一个小文件开始。
只保存在手机里，使用起来很方便，但换设备、误删文件或需要回看旧版本时，风险也会跟着出现。MD文件阅读器提供了可选的 Git 云同步，让本地仓库可以同步到你指定的 Gitee、GitHub 或其他支持 HTTPS Git 的私有仓库。
它不是默认开启的云盘功能，也不是把文档交给一个无法控制的第三方空间。仓库地址由你指定，同步开关由你主动打开；只开启本地版本管理时，文档仍然只保存在本机，不会上传网络。
云同步能做什么？
让文档多一份可迁移的副本
本地仓库里的 Markdown 文档，以及它们使用的图片、附件、导入文件和应用相关元数据，可以随仓库一起保存。这样，文档不会只和某一台手机绑定。
新手机接入已有仓库时，可以按提示选择以远端内容为主，把已有资料拉回本地；手机里的内容完整、远端为空时，也可以选择以本地内容为主，完成首次推送。
保留版本历史
云同步建立在本地版本管理之上。保存、新建、删除、重命名、移动或导入后，应用会记录版本；查看版本历史、恢复文件或开始 Git 同步前，也会先记录尚未提交的变化。
版本历史的价值不只是“备份最后一份文件”。当一段文字被误删、一份方案改偏，或者你想回看上周的写法时，可以预览、比较并恢复单个文件的旧版本。
更谨慎地处理冲突
如果同一个文件在手机和远端都被修改，应用不会直接静默覆盖其中一方。完成同步时，会保留主版本，并把另一版本保存为“冲突副本”。你可以比较两份内容，手动整理出最终版本，再删除不需要的副本并重新同步。
这种处理方式更适合重要的 Markdown 文档：同步可以自动化，但最终取舍仍然交给文档的拥有者。
支持日常自动同步
关联成功后，可以手动点击“立即同步”，也可以按需要开启本地变化后的自动同步、每日补偿同步和仅 Wi-Fi 自动同步。建议重要编辑前后各同步一次，并定期到远端仓库网页确认备份确实存在。
适合哪些使用场景？
1. 想把手机里的资料带到其他设备
如果你在手机上阅读和补充 Markdown，在电脑上进行整理，Git 仓库可以作为两端之间的共同资料源。它不会替你解决所有写作协作问题，但能让个人文档的去向更清楚。
2. 需要版本回溯的长期文档
项目说明、研究记录、个人知识库和持续更新的读书笔记，往往比一次性文件更需要历史记录。Git 的版本模型适合保存“这份资料是怎样一步步变成现在这样”的过程。
3. 不想在手机上使用 Git 命令
你仍然可以按平常的方式打开、编辑和保存文档，应用把连接测试、首次同步、提交和拉取等操作收纳在设置页和文件页入口中。
4. 希望自己掌握仓库和权限
仓库可以创建在自己的 Gitee、GitHub 或其他 HTTPS Git 服务中。建议使用专门的私有仓库，并且只给访问令牌授予目标仓库必要的读写权限。
开启 Git 云同步前，需要准备什么？
使用前请确认：
- Android 6.0 或更高版本；
- 已开启“本地版本管理”；
- 一个专门用于文档备份的私有仓库；
- HTTPS 仓库地址、Git 用户名和具备必要读写权限的访问令牌；
- 首次同步时可用的稳定网络，最好使用 Wi-Fi。
当前支持 Gitee、GitHub 和“其他 HTTPS Git”。不支持 SSH 地址和 Git LFS；不同服务对单文件大小和仓库容量的限制也可能不同。
访问令牌不要写进仓库地址、Markdown 文档或聊天消息。令牌疑似泄露时，应立即到对应 Git 服务商撤销并重新创建。
开启步骤：从本地版本到第一次同步
第一步：进入配置页
在首页更多菜单，或文件页更多抽屉中，进入“版本管理与 Git 云同步”。文件页的 Git 云同步旁边也提供“立即同步”入口。
第二步：先开启本地版本管理
先打开“本地版本管理”。应用会把当前本地仓库记录为首次基线。只有本地版本管理准备好后，才建议继续配置 Git 云同步。
第三步：选择 Git 服务并填写信息
打开“Git 云文件管理”，选择 Gitee、GitHub 或“其他 HTTPS Git”，再填写：
- HTTPS 仓库地址；
- Git 用户名；
- 访问令牌；
- 实际分支名。
空仓库通常可以使用 main，但仍应以远端仓库实际分支为准。不要填写网页浏览地址、SSH 地址，也不要把用户名或令牌拼进 URL。
第四步：测试并保存
点击“仅测试连接”检查参数；确认连接正常后，使用“测试并保存”。如果本地和远端都已有内容，应用会提示你选择首次同步方向。
第五步：确认远端结果
完成首次同步后，到 Gitee、GitHub 或其他 Git 服务的仓库网页确认文档已经出现。确认成功后，再按需要开启自动同步、每日补偿同步或“仅 Wi-Fi 自动同步”。
首次同步应该选哪个方向？
可以用下面的规则判断：
| 实际情况 | 首次同步方向 |
|---|---|
| 手机内容完整，远端是新建的空仓库 | 以本地为主，推送到远端 |
| 新手机接入已有仓库 | 以远端为主，拉取到手机 |
| 手机和远端都有内容 | 按页面提示选择主版本，另一方保留为冲突副本 |
第一次同步前，建议先确认本地仓库和远端仓库中哪一份是“应该保留的资料源”。如果双方都有重要变更，不要急着清理冲突副本，先逐份比较。
日常怎么使用？
最简单的日常流程是：
- 在本地仓库打开或新建 Markdown 文档；
- 编辑并点击保存；
- 需要立即备份时，在文件页更多抽屉点击“立即同步”；
- 如果开启了自动同步，让应用在条件满足时完成同步；
- 定期查看远端仓库，确认同步结果和文件数量符合预期。
如果同时在电脑和手机上修改同一文件，尽量先同步再继续编辑，减少冲突。发生冲突后，保留副本、比较内容、整理主文件，再重新同步，是比直接删除其中一份更稳妥的做法。
关闭云同步会发生什么？
“解除 Git 云关联”会清除应用中的访问令牌和远端配置，但保留本地文档、本地历史以及远端已有文件。关闭本地版本管理只会停止生成新版本，不会自动删除已有历史。
需要注意的是，应用默认仓库存放在应用私有目录，卸载应用可能连同本地仓库一起删除。准备换机或卸载前，应确认整份仓库已经同步或另行备份；仅备份主 Markdown 文件，无法完整恢复书架、封面、分组、阅读位置和统计等元数据。
Git 云同步适合把 Markdown 当作长期资料来管理的人。它不要求你改变写作习惯，却能为文档增加一份由自己掌控的远端副本，以及一条可以回头查找的版本路径。