用 Git 同步 Obsidian：多设备轻量方案

多台设备同时用 Obsidian，核心问题只有一个：

怎么让同一个 Vault 稳定同步、保留版本历史，并能随时加新设备。

本地 Vault + GitHub Private Repository + Obsidian Git

整个架构很简单：

Mac 本地 Vault    Windows 本地 Vault    Linux / 任意台
      ↕                  ↕                  ↕
               └────── GitHub Private ──────┘

GitHub 只负责同步和版本管理，真正工作的文件始终保存在本地。

---

一、为什么选 Git

这个方案主要适合以下场景：

• Vault 以 Markdown、JSON、YAML、图片为主

• 已经会用 Git / GitHub

• 会用 Codex、Claude Code、VS Code 等工具直接操作 Obsidian 文件

• 希望除了同步，还能保留完整修改历史

• 不需要两台设备同时编辑同一篇笔记

• 设备数量不固定：想加几台加几台

相比网盘同步，Git 有几个明显优势。

1. 所有文件始终在本地

Mac：

~/Documents/Obsidian/MyVault

Windows：

D:\Obsidian\MyVault

Linux：

~/Documents/Obsidian/MyVault

Obsidian、Codex、VS Code 都直接操作本地文件，不需要处理云盘占位文件和下载状态。

2. 同步之外，还有版本历史

每次修改都会形成 Commit。

以后文章被 AI 改坏了，或者想找回几天前的版本，可以直接回滚。

3. Markdown 天然适合 Git

Obsidian 的核心文件都是纯文本：

.md
.json
.yaml
.css
.js

即使产生冲突，也比 Word、PPT、Excel 更容易处理。

---

二、整体架构怎么设计

建议创建一个 GitHub Private Repository，例如：

obsidian-vault

Vault 本身保持正常目录结构：

MyVault/
├── 00 Inbox/
├── Notes/
├── Projects/
├── Articles/
├── Resources/
├── Templates/
├── assets/
├── AGENTS.md
├── .obsidian/
├── .gitignore
└── README.md

其中 GitHub Repository 设置为：

Private

Private 仓库负责：

跨设备同步
+
版本历史
+
远程备份

但不要把 Private Repository 当密码保险箱。

以下内容建议永远不要提交：

API Key
Token
密码
证书
.env
公司高度敏感资料

---

三、具体怎么配置

1. Mac 初始化

假设现有 Vault 在：

cd ~/Documents/Obsidian/MyVault

初始化：

git init
git branch -M main

关联 GitHub：

git remote add origin git@github.com:YOUR_NAME/obsidian-vault.git

第一次提交：

git add .
git commit -m "init obsidian vault"
git push -u origin main

---

2. 其他设备拉下来

每台新设备流程一样，台数不限：

git clone git@github.com:YOUR_NAME/obsidian-vault.git

例如放到：

Windows   D:\Obsidian\MyVault
Linux     ~/Documents/Obsidian/MyVault

然后：

Obsidian
→ Open folder as vault
→ 指向对应本地路径

至此，新设备接进同一套同步。

---

3. .obsidian 不要全部忽略

不建议直接：

.obsidian/

否则 Mac 和 Windows 的插件、主题、快捷键会逐渐不一致。

建议同步：

.obsidian/plugins/
.obsidian/themes/
.obsidian/snippets/
.obsidian/hotkeys.json
.obsidian/appearance.json

但忽略设备相关状态：

# Obsidian workspace
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache/
 
# Trash
.trash/
 
# macOS
.DS_Store
 
# Windows
Thumbs.db
Desktop.ini
 
# Secrets
.env
.env.*
*.key
*.pem
secrets/
credentials/
 
# Temp
*.tmp
*.temp

一个简单原则：

同步配置，不同步现场。

插件、主题、快捷键同步。

当前打开哪些页面、窗口位置，不同步。

---

4. 用 Obsidian Git 自动化

手动同步需要：

git pull
git add .
git commit
git push

长期使用会比较烦，所以可以安装 Obsidian Git 插件，每台设备都装，配置相同。

建议配置：

Pull on startup
开启
 
Auto Commit
10～20 分钟
 
Auto Push
开启
 
Commit-and-Sync
开启

这样日常流程变成：

打开 Obsidian
↓
自动 Pull
↓
正常写笔记
↓
自动 Commit
↓
自动 Push

Git 基本退到后台。

---

四、真正需要遵守的规则

这套方案其实只需要记住几条。

规则一：换设备，先 Pull

例如：

设备 A 写完
↓
Push
 
换设备 B
↓
Pull
↓
开始写

不要：

设备 A 没 Push
↓
设备 B 又修改同一个文件

否则容易冲突。

---

规则二：不要过度自动 Commit

没必要每分钟提交一次。

推荐：

10～30 分钟

或者完成一个阶段之后提交。

好的 Commit：

Update AI workflow article
Add Git sync notes
Update project research

而不是：

backup 10:01
backup 10:02
backup 10:03

Git History 本身也应该有可读性。

---

规则三：知识库和公开博客分开

整个 Vault 建议保持 Private：

obsidian-vault
Private

博客单独一个仓库：

blog
Public

架构：

Obsidian Vault
Private
      │
      ↓
筛选需要发布的文章
      │
      ↓
Public Blog Repo
      │
      ↓
Cloudflare Pages

不要直接把整个 Obsidian Vault 暴露给博客系统。

以后可以进一步用 Skill 或脚本自动完成：

Obsidian 文章
↓
复制 Markdown
↓
处理图片
↓
生成 Front Matter
↓
同步 Blog Repo
↓
Git Push
↓
Cloudflare 自动发布

---

最终这套结构其实很简单：

                    GitHub Private
                         ↑ ↓
        ┌──────────┬──────────┴──────────┬──────────┐
        ↓          ↓                     ↓          ↓
   Mac Obsidian   Windows Obsidian    Linux/更多台 Obsidian
        ↕          ↕                     ↕
   Codex / CLI   Codex / CLI          Codex / CLI
 
                         ↓
                   Public Blog Repo
                         ↓
                  Cloudflare Pages

每个工具只负责一件事：

Obsidian： 写和组织内容
Git： 管理变化
GitHub Private： 跨设备同步和备份
Codex： 直接操作本地知识库
Public Repo： 对外发布

如果本来就使用 Git，同时又希望 Obsidian 成为自己的本地 AI 工作空间，那么：

Local First + GitHub Private，是一套足够轻量、稳定，而且可以长期使用的方案。