Obsidian + GitHub：免费同步笔记的完整思路

我最早折腾 Obsidian 同步，是因为不太想一开始就为同步付费。

Obsidian 本身是免费的，笔记也都在本地。写久了以后，多设备同步就变成了一个绕不开的问题。官方 Obsidian Sync 当然省心，打开就能用，也有端到端加密和版本历史。但如果只是个人笔记，或者还在试用 Obsidian 的阶段，很多人会先想找一个免费的办法。

GitHub 就是其中一个办法。

它的思路不复杂：把 Obsidian 的库当成一个 Git 仓库，电脑上写完笔记后提交到 GitHub，另一台电脑再从 GitHub 拉下来。这样，GitHub 充当中间仓库，Git 负责记录变化，Obsidian 继续负责写笔记。

这篇不写成一步一步的安装教程，主要讲这个方案为什么成立，以及真正用久之后会遇到什么问题。

Obsidian 为什么可以这样同步

Obsidian 的笔记不是存在某个封闭数据库里，而是直接存在本地文件夹里。

一篇笔记通常就是一个 .md 文件。图片、PDF、附件，也只是文件夹里的普通文件。你可以用 Obsidian 打开它们，也可以用 VS Code、Typora、系统自带文本编辑器打开它们。

而 Git 最擅长管理的就是文件变化，尤其是文本文件变化。Markdown 本质上也是文本，所以 Obsidian 笔记放进 Git 仓库里，并没有什么特别违和的地方。

Git 不关心这些文件是不是笔记。它只会记录：

• 哪些文件新增了
• 哪些文件被修改了
• 哪些文件被删除了
• 这次修改和上次有什么不同

GitHub 则负责保存一份远程版本。不同设备都和这份远程版本同步。

这个方案实际怎么运转

日常使用时，大概是这样的：

1. 在电脑 A 上打开 Obsidian
2. 先拉取 GitHub 上的最新内容
3. 写笔记、改笔记、贴图片
4. 把这次修改提交到 Git
5. 推送到 GitHub
6. 在电脑 B 上拉取最新内容
7. 继续写

如果你熟悉命令行，就是 pull、add、commit、push 这几件事。

如果不想一直敲命令，可以用 Obsidian Git 插件。这个插件是这套方案里很关键的一环。

它不只是把 commit、pull、push 做成按钮，而是可以设置定时自动拉取、定时自动提交、定时自动推送。配置好以后，日常使用其实很接近“打开 Obsidian 正常写，插件在后台帮你同步”。

不过这里有个地方要先说清楚：GitHub 同步和网盘同步的底层逻辑还是不一样。

网盘同步通常是后台自动检测文件变化，然后自动上传、自动下载。Git 的同步本来是 pull、commit、push 这些明确动作。但 Obsidian Git 插件把这些动作自动化之后，使用负担会小很多。

这也是它的优点和缺点。

优点是每次变化都有记录，出问题时可以回头看。缺点是你最好还是知道它在做什么。它可以很省心，但不是完全不需要理解。

我觉得它适合什么人

如果你已经会一点 Git，这个方案很自然。

Obsidian Vault 就像一个很轻量的项目仓库。只不过平时项目里放的是代码，这里放的是 Markdown 笔记。

它比较适合这些情况：

• 主要在电脑端写笔记
• 想免费同步 Obsidian
• 希望保留完整版本历史
• 能接受一点 Git 的概念，或者愿意用 Obsidian Git 插件把日常操作自动化
• 平时会用 GitHub、GitLab 或 Gitee
• 不希望笔记被锁在某一个云笔记产品里
• 用 Obsidian 写技术笔记、项目记录、博客草稿、学习资料

如果你平时完全不接触 Git，也不是不能用，只是需要先理解几个词：仓库、提交、推送、拉取、冲突。

这些概念不难，但绕不过去。

如果你主要在桌面端使用，Obsidian Git 插件配置好以后，省心程度其实比我一开始预期的高。

最小配置大概是什么样

如果用最朴素的方式，大概是：

1. 在 GitHub 新建一个私有仓库
2. 在电脑上创建一个 Obsidian Vault
3. 把这个 Vault 初始化成 Git 仓库
4. 连接到 GitHub 远程仓库
5. 把本地文件推送上去
6. 另一台设备 clone 这个仓库
7. 用 Obsidian 打开 clone 下来的文件夹

命令行大概长这样：

git init
git add .
git commit -m "init obsidian vault"
git remote add origin git@github.com:yourname/your-vault.git
git push -u origin main

另一台电脑上：

git clone git@github.com:yourname/your-vault.git

然后在 Obsidian 里选择“打开本地文件夹”。

Obsidian Git 插件强烈建议安装。仓库配置好以后，它可以把日常同步成本降到很低。

真正影响体验的是使用习惯

这个方案能不能用得稳定，不只看配置，也看同步策略。

如果不用插件，最重要的一条是：换设备写之前，先拉取最新内容。

比如你晚上在电脑上写了一篇笔记，但忘了 push。第二天又在另一台电脑上改同一篇笔记，后面就容易冲突。

冲突不是灾难，Git 本来就能处理冲突。但对笔记来说，冲突会打断写作节奏。你本来只是想记录一点东西，结果突然要判断哪一段该保留，体验就很差。

如果用 Obsidian Git 插件，我更推荐把这些动作交给它定时处理：

1. 定时自动 pull，保证本地尽量拿到最新版本
2. 定时自动 commit，把本地修改保存成 Git 历史
3. 定时自动 push，把修改推到 GitHub
4. 尽量不要在两台设备上同时改同一篇笔记

这样配置后，日常就不用总想着“我是不是该提交了”。

手机端是这个方案里比较麻烦的一环

桌面端最好处理。Mac、Windows、Linux 都可以正常用 Git。

Android 也有一些办法，比如配合 Git 工具、Termux 或其他同步方案。能折腾，但不算特别优雅。

iPhone 和 iPad 会更麻烦一些。常见做法是借助 Working Copy 这类 Git 客户端，再和 Obsidian 配合使用。这个方案能跑起来，但对新手不算友好。

所以如果你的主要需求是手机端高频写作，GitHub 同步未必是最省心的选择。

图片和附件会慢慢变成问题

刚开始用 GitHub 同步 Obsidian 时，大家通常关心的是能不能同步成功。

但用一段时间后，另一个问题会冒出来：图片和附件。

Markdown 文件很小。几百篇、几千篇笔记，体积通常也还好。真正让仓库变大的，往往是这些图片和文档附件。

尤其是截图。平时看到网页、软件界面、配置步骤，随手一贴，很快 attachments 文件夹就会堆起来。

这会带来仓库越来越大、每次拉取更新都很慢。

Git 能记录这些文件，但 Git 不会帮你判断一张图片有没有被笔记引用，也不会帮你整理文件名，更不会自动清理无用附件。

所以 Obsidian + GitHub 这个方案，前半段解决的是同步问题；用久之后，真正需要维护的是仓库结构。这里推荐一下我开发的 NotePic OSS 插件，能够将附件资源上传到 OSS 存储并清理掉原本的本地资源。

这个方案的边界

GitHub 同步 Obsidian 不是万能方案。

它适合愿意做一次配置的人。你会得到免费的远程仓库、清楚的版本历史、很好的可迁移性。

我觉得比较现实的判断是：

• 如果你已经熟悉 Git，可以直接试
• 如果你愿意跟着教程配置一次 Obsidian Git 插件，也值得试
• 如果你的核心需求是手机端无感同步，官方 Sync 还是更稳
• 如果你的笔记里图片很多，要提前考虑附件管理

最后

Obsidian + GitHub 把笔记重新变成了一组你能直接看到、能备份、能迁移、能回滚的文件。

这件事对长期写笔记的人很有吸引力。今天用 Obsidian，明天换别的 Markdown 工具，文件还在。某天误删了一段内容，也能从 Git 历史里找回来。

参考来源

• GitHub Pricing
• GitHub Docs: GitHub’s products
• Obsidian Pricing
• Obsidian Git Plugin