Obsidian Git 同步教程：GitHub 备份、插件设置和多端拉取完整流程

同步提醒

Git 是所有 Obsidian 同步方案里门槛最高的一种。

如果你只是想让几台设备看到同一份笔记，优先考虑 Obsidian Sync、iCloud、坚果云、Syncthing 这类方案。

Git 更适合有明确版本管理需求的人。比如你希望知道每次改了什么，能回到某个历史版本，或者本身就很爱折腾 Obsidian：今天试一个插件，明天换一套主题，后天改 CSS 片段、代码块、模板和各种配置。只要折腾前提交过一次，就算后面把整个库搞乱了，也可以比较快地恢复到原来的状态。

这套方案更适合两类人，一类是确实需要跨 Mac、Windows、Android、iPhone 多平台同步的人，另一类是对版本管理有强需求，并且愿意接受命令行和 GitHub 学习成本的人。如果只是想省心同步笔记，不建议为了 Git 而 Git，因为整个配置和维护过程确实比普通网盘同步麻烦。

Git 同步的流程大概是这样的：

只要下面任何一步看起来太麻烦，都不建议硬上，因为后续维护时也会继续遇到类似问题。

不同设备的操作会分开讲，但核心顺序始终一样：

1. 先准备一个远程仓库
2. 在电脑上把 Obsidian 笔记库变成 Git 仓库，并推送到远程
3. 其他设备从同一个远程仓库拉取这份笔记库
4. 日常使用时，写之前先拉取，写完后再提交和推送

电脑端可以直接用 Obsidian Git 插件处理这些动作。手机端限制更多，所以 Android 和 iPhone 会改用专门的 Git App 来负责同步，Obsidian 只负责打开和编辑笔记。

Obsidian Git 同步教程

注册 GitHub 账号

使用 Git 同步之前，先准备一个远程仓库。GitHub 和 Gitee 都可以，本文以 GitHub 为例。

• GitHub 官网
• Gitee 官网

注册完成后，进入自己的仓库列表，点击右上角的 New。

仓库名可以直接写 obsidian，也可以换成你自己的笔记库名字。这里一定要把仓库设成 Private，不要选 Public。Obsidian 里往往会有个人笔记、截图、附件，甚至插件配置和临时文件，不适合公开放在网上。

创建完成后，GitHub 会给你一个仓库地址。后面要用的就是这个地址，比如图里这一段：

https://github.com/leonlin21/obsidian.git

你实际操作时，要复制自己页面上的地址，不要照抄上面这个示例。

在本机安装 Git

Git 需要先安装到电脑上，Obsidian 的 Git 插件只是调用它，不会替你安装底层工具。

官网地址：https://git-scm.com/downloads

如果你习惯让 AI 辅助操作，可以直接把这个网址发给 AI，让它按照你的系统一步步教你安装。

安装完成后，再次输入：

git --version

能看到版本号，就说明 Git 已经可以用了。

初始配置 Git

第一次使用 Git 时，需要告诉 Git 提交记录里显示什么名字和邮箱。打开终端工具，Windows 用 PowerShell，Mac 用终端，然后输入下面两行。

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

这里的邮箱建议填你的 GitHub 注册邮箱。它只影响提交记录里显示的作者信息，不等于 GitHub 登录密码。

初始化本地 Obsidian 仓库

开始前先备份一次你的 Obsidian 笔记库。Git 本身是版本管理工具，但第一次配置时最好不要把它当成唯一保险。

先找到你的 Obsidian 笔记库路径，然后在终端里进入这个文件夹。

Windows 示例：

cd "C:\Users\你的用户名\Documents\Obsidian\你的库名"

Mac 示例：

cd "/Users/你的用户名/Documents/Obsidian/你的库名"

双引号用来包住路径，防止空格或中文导致终端识别出错。路径简单、没空格的话可以不加。

进入笔记库后，依次执行：

git init
git branch -m main

git init 执行成功后，笔记库根目录会多出一个 .git 隐藏文件夹。Finder 或资源管理器默认可能看不到它，截图里标出的就是这个文件夹。

这一步可以先按图里的顺序理解，再回到正文复制命令：

接下来要在笔记库根目录创建一个 .gitignore 文件。注意，这个文件放在笔记库根目录，别放进 .git 文件夹里。

.gitignore 的作用是告诉 Git 哪些文件不要同步。下面这份配置适合新手先用：

# ===== 最推荐的通用忽略项（新手/多设备首选） =====

# 1. 设备特定的界面布局（最重要，强烈推荐忽略）
# 不同电脑和手机的窗口位置、打开的标签页不一样，容易频繁冲突
.obsidian/workspace.json
.obsidian/app.json

# 2. 系统自动生成的垃圾文件
.DS_Store
Thumbs.db
.directory

# 3. Obsidian 自己的回收站
.trash/

# ===== 可选进阶忽略（根据你的情况选） =====

# 4. 整个 .obsidian 文件夹（最简单粗暴）
# 适合：不想同步插件设置、主题、快捷键，每台设备自己配一次
# .obsidian/

# 5. 保护隐私，避免密钥泄露（推荐）
# 很多插件的 data.json 里可能存 API Key、Token
.obsidian/plugins/*/data.json

# 6. 大文件和附件（仓库会变大，同步会变慢）
# 如果你有大量图片、PDF、视频，建议忽略或单独用其他方式同步
# attachments/
# *.pdf
# *.mp4

# 7. 其他常见缓存和临时文件
*.log
*.tmp
.cache/

想完全不同步 .obsidian 配置的话，把 # .obsidian/ 前面的 # 删掉就行。新手不建议一开始就这么做，因为插件、主题和快捷键也会一起不同步。

安装 Obsidian Git 插件

如果你还没装过第三方插件，可以先看这篇：Obsidian 最新全平台插件安装教程。已经熟悉插件安装的话，直接继续下面的步骤。

打开 Obsidian 的第三方插件市场，搜索 Git

安装后进入插件设置，重点改两个地方。

第一个是 Auto commit-and-sync interval，它决定 Obsidian 每隔多久自动提交并同步一次。图里填的是 1 分钟，适合测试；长期使用可以改成 5 或 10 分钟，减少太频繁的同步。

第二个是 Pull on startup，建议打开。它的作用是每次启动 Obsidian 时先从远程仓库拉取最新内容，能减少多台设备交替使用时的冲突。

其他选项先保持默认。Git 同步的坑很多，初期不要同时改太多设置，先让最基础的提交、推送、拉取跑通。

将本地笔记库同步到 GitHub

接下来回到终端。无论 Windows 还是 Mac，都要先进入你的 Obsidian 笔记库路径。

Windows 示例：

cd "C:\Users\你的用户名\Documents\Obsidian\你的库名"

Mac 示例：

cd "/Users/你的用户名/Documents/Obsidian/你的库名"

和前面一样，替换双引号里面的路径即可。

先把 GitHub 仓库地址加到本地仓库里：

git remote add origin https://github.com/你的用户名/你的仓库名.git

这条命令成功时通常没有任何提示。

然后依次执行下面三条命令：

git add .
git commit -m "Initial commit: Add all vault files"
git push -u origin main

这三条命令分别做三件事：

• git add .：把当前笔记库里的文件放进待提交区。
• git commit ...：生成一次本地版本记录。
• git push ...：把本地版本上传到 GitHub，并把本地 main 分支和 GitHub 的 main 分支关联起来。

执行 git push -u origin main 后，终端会先要求输入用户名。

用户名就是你的 GitHub 用户名，头像菜单里显示的那一串，比如图里的 leonlin21。

接下来会要求输入密码。

不要在这里输入 GitHub 账号密码。GitHub 现在要求用 Token，也就是下面要生成的那串密钥。

进入这个页面：https://github.com/settings/tokens

左侧选 Tokens (classic)，右上角点 Generate new token，然后选择 Generate new token (classic)。

进去后这样填：

• Note：写一个你能看懂的名字，比如 Obsidian Git 同步。
• Expiration：可以选 90 days。如果你不想以后重新生成，也可以选 No expiration，但安全性会差一点。
• Select scopes：只勾选 repo。

然后拉到页面底部，点击 Generate token。

生成后会出现一串以 ghp_ 开头的内容。这个 Token 只显示一次，立刻复制保存。回到终端，在 Password for ... 后面直接粘贴。

终端里粘贴密码或 Token 时，屏幕通常不会显示任何字符，这是正常的。粘贴后直接按回车。

如果看到类似下面的结果，就代表第一次推送成功了：

branch 'main' set up to track 'origin/main'.

推送后可以回到 GitHub 仓库首页检查一次。左上角仓库名旁边应该能看到 Private，说明仓库没有公开；文件列表上方会显示最新提交记录，比如 vault backup: 2026-05-28 09:51:23，右侧也会显示一共有几次提交。

如果 GitHub 页面里能看到刚刚同步上来的文件、最新提交时间显示为 now 或几分钟前，就说明这次同步已经成功。后面 Obsidian Git 插件自动同步后，也可以用同样的方法回来检查。

本地笔记库现在已经和 GitHub 仓库关联起来。后面在 Obsidian 里修改笔记时，插件就可以按你设置的时间自动提交并同步。

插件使用细节

配置完成后，Obsidian 右侧会出现 Git 插件的 Source Control 面板。下面这张图是当前插件界面的真实截图，日常会用到的按钮基本都在这里。

先看顶部工具栏前五个按钮。它们主要负责把本机改动保存下来，并把已经保存的内容上传到 GitHub。

1. 提交并同步：最适合新手日常使用。它会把当前改动保存成一次版本记录，并继续同步到 GitHub。
2. 只提交：只在本机生成版本记录，不会上传到 GitHub。你只是想先保存一个本地版本时，用它。
3. 全部暂存：把所有改动先放进待提交区。对新手来说，平时不需要单独点它。
4. 全部取消暂存：把已经放进待提交区的内容拿出来。
5. 推送到 GitHub：把本机已经提交过的内容上传到远程仓库。

接着看 6 到 10，会用到拉取、刷新、提交说明，以及文件是否已经暂存。

6. 从 GitHub 拉取：把远程仓库里的新内容下载到本机。换设备写笔记前，建议先拉取一次。
7. 切换显示方式：改变变更列表的展示方式，文件多的时候可以试试。
8. 刷新状态：让插件重新检查当前有哪些文件变化。如果你刚改完文件，但面板没反应，先点它。
9. Commit Message：提交说明。你可以写「今天整理笔记」「补充同步教程」这类简单描述。如果留空，插件会使用你在设置里配置的默认提交说明。
10. Staged Changes：已经暂存、准备提交的文件。

最后看文件变更区，里面会显示哪些文件还没暂存，以及右侧的小操作按钮。

11. Changes：已经发生变化，但还没暂存的文件。
12. 变更区右侧的小按钮：+ 是把文件加入暂存，回转箭头是丢弃当前改动。丢弃会把文件恢复到上一次 Git 记录里的状态，这个按钮要谨慎点。

日常用法很简单：写完笔记点 提交并同步，面板没更新就点 刷新状态。其他按钮需要时再回来查。

如果你在多台设备之间切换，建议养成两个习惯：

1. 打开 Obsidian 后，先点一次 从 GitHub 拉取，确认本机是最新内容。
2. 关闭电脑或换设备前，点一次 提交并同步，确认当前改动已经上传。

Git 同步最容易出问题的地方，是两台设备都在旧版本上继续修改同一份文件。这样很容易产生冲突，最后需要手动判断保留哪一段内容。

在 Windows 拉取同步

确认 Mac 端成功推送到 GitHub 后，Windows 端不需要重新 git init，也不需要重新建仓库。它要做的是把同一个远程仓库克隆下来，然后用 Obsidian 打开这个文件夹。

先在 Windows 上安装 Git。推荐直接下载 Git for Windows：

https://git-scm.com/download/win

Windows 11 也可以打开 PowerShell，执行下面这条命令安装：

winget install --id Git.Git -e --source winget

安装时一路默认即可。装完后打开 Git Bash，先检查 Git 是否能用：

git --version

第一次在 Windows 上用 Git，也要配置一次提交用户名和邮箱：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

邮箱建议和 GitHub 注册邮箱保持一致。

接着选择一个你想存放 Obsidian 笔记库的位置。比如你想放在 D:\ObsidianVaults，可以在 Git Bash 里输入：

mkdir -p /d/ObsidianVaults
cd /d/ObsidianVaults

然后克隆 Mac 端已经同步过的远程仓库：

git clone https://github.com/你的用户名/你的仓库名.git

如果你用的是 Gitee，就把地址换成自己的 Gitee 仓库地址。克隆完成后，D:\ObsidianVaults 下面会多出一个仓库文件夹，里面就是你的 Obsidian 笔记、.git 文件夹和前面设置好的 .gitignore。

接下来打开 Obsidian，选择「打开文件夹作为库」，然后选中刚才克隆出来的那个文件夹。打开后，Windows 端看到的就是 Mac 端已经推送到 GitHub 的那份笔记。

如果你希望 Windows 端也能自动同步，需要再安装一次 Obsidian Git 插件。流程和 Mac 上一样：

1. 打开 Obsidian 设置。
2. 进入「第三方插件」。
3. 搜索并安装 Obsidian Git。
4. 启用插件。

插件启用后，先手动拉取一次最新内容。可以 Ctrl+P 打开命令面板，搜索并执行：

Git: Pull

也可以打开右侧 Git 插件面板，点击 从 GitHub 拉取 按钮。第一次拉取或推送时，如果 Windows 弹出 GitHub 登录或认证窗口，按提示登录，或者粘贴前面生成过的 GitHub Token。Windows 的 Git Credential Manager 通常会帮你记住这次认证，后面就不用反复输入。

插件设置可以和 Mac 保持一致。至少建议打开 Pull on startup，这样每次打开 Obsidian 时，Windows 会先从 GitHub 拉取一次最新内容。自动提交和同步间隔也可以沿用 Mac 上的设置，比如 5 或 10 分钟。

Windows 端最容易遇到的是下面几个问题：

一直要求输入密码怎么办？

GitHub 现在不能直接用账号密码推送。遇到这种情况，重新粘贴 GitHub Token，或者在 Git Bash 里执行：

git config --global credential.helper manager-core

Mac 和 Windows 来回同步，文件换行会不会出问题？

可以在 Windows 的 Git Bash 里执行：

git config --global core.autocrlf input

这样能减少不同系统之间因为换行符产生的额外变化。

Obsidian Git 插件找不到 Git 怎么办？

如果你用的是正常安装的 Git for Windows，一般不会遇到这个问题。如果插件提示找不到 Git，可以在插件设置里手动指定 git.exe 路径。常见位置类似：

C:\Program Files\Git\bin\git.exe

第一次克隆或拉取很慢正常吗？

正常。第一次会把整个笔记库和附件都下载下来，笔记多、图片多时会比较慢。后面只同步新增和修改的内容，速度会快很多。

Windows 上改完笔记后怎么收尾？

和 Mac 一样，关闭电脑或换设备前，先点一次 提交并同步。换回 Mac 或其他设备时，打开 Obsidian 后先点一次 从 GitHub 拉取。

在安卓手机拉取同步

安卓端不建议直接用 Obsidian Git 插件同步。手机上的仓库稍微大一点，插件就更容易卡住、报错，后面排查起来也麻烦。

用 Obsidian App 加 GitSync App：Obsidian 负责打开和编辑笔记，GitSync 负责把 GitHub 或 Gitee 仓库同步到手机本地文件夹。

GitSync 是一个移动端 Git 同步工具，支持 Android，也支持 HTTPS、SSH 和 GitHub OAuth。它可以克隆远程仓库，也可以执行拉取、提交和推送。安卓上还可以设置打开应用时同步、定时同步、快捷磁贴同步。

GitSync 地址：

https://github.com/ViscousPot/GitSync

安卓手机上先准备两个 App：

1. 安装 Obsidian。
2. 安装 GitSync，可以从 Google Play、F-Droid 或 GitHub Releases 下载。

安装完成后，先打开 GitSync，新建一个同步仓库。里面要填的信息和前面 Mac、Windows 用的是同一个远程仓库：

• Remote URL：粘贴你的 GitHub 或 Gitee 仓库地址。
• Username：填写 GitHub 或 Gitee 用户名。
• Token：粘贴前面生成过的个人访问令牌。
• Sync Directory：选择手机里准备用来存放 Obsidian 笔记库的文件夹。

如果你用 GitHub，也可以在 GitSync 里走 GitHub OAuth 登录。新手用 HTTPS 地址加 Token 更容易和前面的教程保持一致。

第一次同步时，GitSync 会把远程仓库里的笔记克隆到手机本地。这个过程可能需要几分钟，笔记和附件越多，时间越长。同步完成后，再打开 Obsidian，选择「打开文件夹作为库」，选中刚才 GitSync 同步出来的那个文件夹。

打开以后，安卓端看到的就是 Mac 和 Windows 已经同步到远程仓库的同一份笔记。

GitSync 里可以按自己的使用习惯开启自动同步。比较稳的设置是：

• 打开 Obsidian 前先同步一次。
• 关闭 Obsidian 后再同步一次。
• 或者设置每 15 到 30 分钟同步一次。
• 只在 Wi-Fi 下同步，避免流量消耗太大。

这里不用重新写 .gitignore，因为它已经跟着仓库一起同步到了手机。Mac 上忽略掉的文件，手机端也会按同一套规则处理。

安卓端要注意两件事：

1. 不要再启用 Obsidian Git 插件。GitSync 和 Obsidian Git 插件同时操作同一个仓库，容易互相打架。
2. 手机上改完笔记后，最好手动确认 GitSync 已经同步成功，再换回电脑继续写。

如果手机端同步失败，先排查 Token 是否过期、仓库地址是否填错、手机是否限制了 GitSync 后台运行。安卓系统的省电策略有时会阻止后台同步，如果经常同步不及时，可以把 GitSync 加进电池优化白名单。

在 iPhone 拉取同步

iPhone 端用 Git 同步会比 Android 稍微麻烦一点。原因主要在 iOS 的文件访问限制，Obsidian Git 插件在手机上也不够稳定，容易遇到识别不了仓库、拉取失败或者插件崩溃。

iPhone 上更稳的方案是 Working Copy 加 Obsidian。Working Copy 负责克隆、拉取、提交和推送，Obsidian 负责打开和编辑笔记。

先看这张图，理解 iPhone 端几个东西的关系：

先生成 iCloud 里的 Obsidian 专属文件夹

这一步很容易被跳过，但它会直接影响后面能不能正常打开库。

不要自己去 iCloud 云盘里手动新建一个叫「Obsidian」的普通文件夹。iPhone 端 Obsidian 更稳定的做法，是使用 Obsidian App 自己创建的专属文件夹。这个文件夹会出现在 iCloud 云盘里，并且带有 Obsidian 图标。

操作方式是：

1. 从 App Store 安装 Obsidian。
2. 打开 Obsidian。
3. 选择创建一个新的库。
4. 位置选择 iCloud。
5. 先创建一个临时库也可以，重点是让 Obsidian 先把 iCloud 里的专属文件夹生成出来。

完成后，打开 iPhone 的「文件」App，进入 iCloud 云盘，你应该能看到一个带有 Obsidian 图标的「Obsidian」文件夹。

如果你这里找不到这个文件夹，先参考我的另一篇 Obsidian iCloud 同步教程。那篇文章专门讲了为什么必须用 Obsidian 自己生成的文件夹，以及 Mac 和 iPhone 之间怎么确认路径是否正确。

安装 Working Copy

接着从 App Store 安装 Working Copy。它是 iOS 上比较成熟的 Git 客户端，可以完整处理克隆、拉取、提交和推送。

Working Copy 是付费 App。如果你只是偶尔在手机上查看笔记，可能没必要折腾到这一步；如果你确实想让 iPhone 也加入同一套 Git 同步链路，它会比直接在 Obsidian 里跑 Git 插件稳很多。

在 Working Copy 里克隆仓库

打开 Working Copy，点击右上角「+」，选择 Clone repository。

这里填入你前面 Mac 或 Windows 使用的同一个远程仓库地址，可以是 GitHub，也可以是 Gitee。登录时建议继续使用个人访问令牌，也就是前面生成过的 Token。

克隆完成后，进入这个仓库，找到 Status and Configuration，然后选择 Link Repository to Folder。

把仓库链接到 iCloud 云盘里的 Obsidian 专属文件夹下，也就是前面由 Obsidian App 自己生成的那个位置。

路径大概是：

iCloud 云盘/Obsidian/你的笔记库名称

链接完成后，Working Copy 继续管理 Git，Obsidian 可以正常识别并打开这个库。

在 Obsidian iOS 里打开这个库

回到 Obsidian，选择「打开文件夹作为库」，然后找到刚才 Working Copy 链接过去的那个文件夹。

打开后，iPhone 上看到的就是 Mac、Windows 或 Android 已经同步到远程仓库里的同一份笔记。

日常使用流程

iPhone 上的日常顺序尽量固定：

1. 写之前，先打开 Working Copy，执行 Pull。
2. 回到 Obsidian，正常编辑笔记。
3. 写完后，回到 Working Copy，执行 Commit。
4. 最后执行 Push，把手机上的改动推回远程仓库。

也可以用 iOS「快捷指令」做一点自动化，比如设置成打开 Obsidian 时，让 Working Copy 先执行 Pull。不过 iOS 的后台限制比较多，所以不要期待它像电脑一样完全自动同步。

iPhone 端不要再启用 Obsidian Git 插件，让 Working Copy 专门负责 Git，Obsidian 专门负责编辑。另外，不要把库放在 iCloud 云盘的普通文件夹里，优先放在带 Obsidian 图标的专属文件夹里。

如果你主要在 Mac 和 iPhone 之间同步，其实 iCloud 本身已经是最省心的方案。Git 更适合用来做版本记录，或者让 Mac、Windows、Android、iPhone 都围绕同一个远程仓库工作。

总结

Git 同步最大的好处是保留修改记录。每次提交都像给笔记库拍一张快照，可以回头看改过什么，也可以回到某个历史版本。它不挑平台，只要远程仓库还在，Mac、Windows、Android、iPhone 都能用同一份仓库。

代价也很直接：第一次配置比网盘同步麻烦，得搞清楚仓库、提交、推送、拉取和 Token。多设备同时改同一份文件可能冲突，需要你自己判断保留哪段。手机端用 Obsidian Git 插件不够稳定，交给 GitSync 或 Working Copy 更靠谱。

我的选择顺序是：

1. 只在 Apple 设备之间用 → iCloud 最省心。
2. 多平台但不想折腾 → Obsidian Sync、iCloud、坚果云、Syncthing。
3. 需要版本记录或跨 Mac/Windows/Android/iPhone → Git。
4. 决定用 Git → 电脑端 Obsidian Git 插件，Android 用 GitSync，iPhone 用 Working Copy。

Git 能不能稳定用，主要看一个习惯：换设备前先提交推送，换设备后先拉取。养成这个习惯，Git 比网盘更可控；经常忘，它就比什么都麻烦。

相关阅读

如果你还在比较 Obsidian 的同步方式，可以继续看这几篇：

• Obsidian iCloud 同步教程：Mac 和 iPhone 设置方法
• Obsidian 坚果云同步教程
• Obsidian Syncthing 同步教程：Mac、Windows、安卓和 iPhone 多端同步
• Obsidian Remotely Save 同步教程：腾讯云 COS 配置完整指南
• Obsidian 最新全平台插件安装教程

常见问题

执行 git init 没反应正常吗？

正常。

执行 git remote add origin ... 没反应正常吗？

正常。可以用下面这条命令检查：

git remote -v

能看到 GitHub 地址，就说明已经添加成功。

如果提示 remote origin already exists 怎么办？

说明你之前已经添加过远程地址。先查看当前地址：

git remote -v

如果地址不对，再用下面这条命令替换：

git remote set-url origin https://github.com/你的用户名/你的仓库名.git

Token 粘贴后看不到任何字符，是不是没粘上？

终端输入密码时默认不显示字符，也不会显示星号。直接粘贴后按回车即可。

Token 过期后怎么办？

重新进入 GitHub 的 Token 页面生成一个新的。旧 Token 过期只会影响上传和拉取，不会删除你的本地笔记。

我应该同步整个 .obsidian 文件夹吗？

如果你希望不同设备的主题、插件列表、快捷键尽量一致，可以同步一部分 .obsidian 配置。但不建议无脑同步所有插件数据，因为部分插件会把 API Key、Token 之类的敏感信息放进 data.json。

新手可以先用本文的 .gitignore，等同步稳定后再按自己的需求调整。