【干货】使用 Obsidian 的 Git 插件将你的笔记同步到 GitHub 私有仓库

Ne0inhk

21 Mar 2026 — 10 min read

前置条件

在开始之前，请确保你具备以下条件：

Obsidian 安装：已在你的电脑或移动设备上安装了 Obsidian。
Git 安装：
- Windows：从 git-scm.com 下载并安装 Git。
- Mac：使用 Homebrew 安装（brew install git）或从 git-scm.com 下载。
- Linux：使用包管理器安装，例如 sudo apt-get install git（Debian/Ubuntu）或 sudo dnf install git（Fedora）。
GitHub 账号：已注册 GitHub 账号，并启用了双重认证（推荐）。
基本了解：对 GitHub 和 Obsidian 的基本操作有一定了解（无需深入 Git 知识）。

步骤一：创建 GitHub 私有仓库

登录 GitHub：
- 访问 github.com 并登录你的账号。
创建新仓库：
- 点击右上角的 “+” 图标，选择 New repository。
- 填写仓库名称，例如 Obsidian-Notes。
- 选择 Private（私有仓库），确保你的笔记不会公开。
- 暂时不需要勾选 “Add a README file” 或其他选项。
- 点击 Create repository。
获取仓库地址：
- 创建完成后，复制仓库的 HTTPS 或 SSH 地址（例如 https://github.com/你的用户名/Obsidian-Notes.git）。建议使用 HTTPS，初学者更简单。

步骤二：生成 GitHub 个人访问令牌（Personal Access Token, PAT）

GitHub 不再支持密码认证，因此需要 PAT 来进行身份验证。

进入设置：
- 在 GitHub 页面右上角，点击你的头像，选择 Settings。
- 向下滚动到左侧菜单，点击 Developer settings。
创建令牌：
- 点击 Personal access tokens > Fine-grained tokens（推荐，权限更精细）或 Tokens (classic)。
- 点击 Generate new token。
- 如果选择 Fine-grained token：
  - 命名你的令牌，例如 “Obsidian Sync”。
  - 设置过期时间（建议 90 天或自定义）。
  - 在 Repository access 中，选择 Only select repositories，然后选择刚创建的私有仓库。
  - 在 Permissions 中，启用 Contents（读写权限）。
- 如果选择 Classic token：
  - 勾选 repo 权限（包含所有仓库读写权限）。
- 点击 Generate token。
保存令牌：
- 复制生成的令牌，妥善保存（它只会显示一次）。建议存储在密码管理器中。

步骤三：初始化本地 Obsidian 仓库

选择或创建 Obsidian Vault：
- 打开 Obsidian，选择你的笔记 Vault（文件夹）。如果还没有 Vault，可以创建一个新的。
- 假设你的 Vault 文件夹路径为 ~/Obsidian-Notes。
初始化 Git 仓库：
- 打开终端（Windows 使用 Git Bash，Mac/Linux 使用内置终端）。
添加 .gitignore 文件（可选但推荐）：
- 这可以避免同步 Obsidian 的临时文件或设备特定的配置。
提交初始文件：
- 如果提示输入认证，用户名输入你的 GitHub 用户名，密码输入之前生成的 PAT。

推送到 GitHub：

git push -u origin main

重命名本地仓库：

git branch -m master main

提交更改：

git commit -m"Initial commit"

添加所有文件到 Git：

gitadd.

在 Vault 根目录创建一个 .gitignore 文件，排除不想同步的文件，例如：

.obsidian/cache/ .obsidian/workspace.json .obsidian/appearance.json .trash/

将 Vault 文件夹与 GitHub 仓库关联：

git remote add origin https://github.com/你的用户名/Obsidian-Notes.git

初始化 Git 仓库：

git init

导航到 Vault 文件夹：

cd ~/Obsidian-Notes

如果遇到错误 fatal: detected dubious ownership in repository ，不要担心，这是 Git 的安全检查机制触发的，原因是 Git 检测到仓库目录的所有者与当前用户不匹配。这种情况通常发生在目录由其他用户或管理员账户创建、修改，或在外部/共享磁盘上操作时。

解决方法 1：将目录添加到 Git 的安全列表

这是最简单且推荐的解决方案，告诉 Git 信任这个目录。

用户名：你的 GitHub 用户名（Yanxinwu946）。
密码：使用 GitHub 个人访问令牌（PAT）。如果你还没生成 PAT，请参考下面的说明。

继续同步操作：
添加、提交并推送文件到 GitHub：

gitadd.git commit -m"初次提交"git push -u origin main

如果提示输入认证信息：

验证远程仓库：
检查远程仓库是否正确添加：

git remote -v

你应该看到类似以下输出：

origin https://github.com/Yanxinwu946/Obsidian-Notes.git (fetch) origin https://github.com/Yanxinwu946/Obsidian-Notes.git (push)

重新添加远程仓库：
再次运行你之前的命令：

git remote add origin https://github.com/Yanxinwu946/Obsidian-Notes.git

运行安全配置命令：
打开终端（Git Bash、命令提示符或 PowerShell），运行以下命令：

git config --global--add safe.directory "E:/新备份/Documents/Obsidian Vault"

这会标记 Obsidian Vault 目录为安全，绕过所有权检查。

解决方法 2：修改目录所有权（可选）

如果你不希望使用 safe.directory（例如出于安全考虑或问题仍未解决），可以更改目录的所有权，使其与当前用户（T6A/Administrator）匹配。

/t：递归更改目录下所有文件和子目录的所有权。
/c：继续执行，即使遇到错误。

验证更改：
再次运行 dir "E:\新备份\Documents\Obsidian Vault" /q，确认所有者已变为 T6A\Administrator。
重试 Git 命令：
返回步骤 1 的 git remote add origin 命令，继续操作。

更改所有权：
使用 icacls 命令将所有权改为当前用户：

icacls "E:\新备份\Documents\Obsidian Vault" /setowner "T6A\Administrator" /t /c

检查当前所有权：
在命令提示符或 PowerShell 中运行：

dir "E:\新备份\Documents\Obsidian Vault" /q

这会显示目录的当前所有者。

步骤四：在 Obsidian 中安装和配置 Git 插件

安装 Obsidian Git 插件：
- 打开 Obsidian，进入 Settings > Community plugins。
- 如果是第一次使用社区插件，关闭 Safe mode。
- 点击 Browse，搜索 “Obsidian Git”。
- 点击 Install，然后 Enable。
配置插件：
- 进入 Settings > Obsidian Git。
- 基本设置：
  - Vault backup interval：设置为自动提交的间隔，例如 5 分钟（单位：分钟）。
  - Commit message：自定义提交信息，例如 Auto commit from Obsidian。
  - Auto push：启用，以便每次提交后自动推送到 GitHub。
  - Pull updates on startup：启用，确保启动 Obsidian 时自动拉取最新更改。
- 认证设置：
  - 如果使用 HTTPS，在 Username 输入你的 GitHub 用户名，在 Password 输入 PAT。
  - 如果使用 SSH，确保本地已配置 SSH 密钥（见下文“高级设置”）。
- 其他推荐设置：
  - 启用 Auto pull，定期拉取远程更改。
  - 如果 Vault 较大，调整 List files individually 或 Disable on mobile（移动端性能可能较差）。
测试同步：
- 创建一个新笔记，保存后等待插件自动提交（或手动触发：Command Palette > Obsidian Git: Create backup）。
- 检查 GitHub 仓库，确认新笔记是否出现。

步骤五：在其他设备上同步

克隆仓库到新设备：
- 确保新设备已安装 Git 和 Obsidian。
- 输入 GitHub 用户名和 PAT 进行认证。
打开 Vault：
- 在 Obsidian 中，选择 Open folder as vault，导航到克隆的文件夹（例如 Obsidian-Notes）。
安装和配置 Git 插件：
- 重复步骤四的插件安装和配置。
- 确保所有设备的插件设置一致（例如自动提交间隔、认证信息）。
同步测试：
- 在一台设备上编辑笔记，等待自动提交和推送。
- 在另一台设备上启动 Obsidian，确认是否自动拉取了更改。

打开终端，克隆仓库：

git clone https://github.com/你的用户名/Obsidian-Notes.git

步骤六：移动端设置（可选）

Obsidian Git 在移动端的性能较差（由于使用 JavaScript 实现的 isomorphic-git），但仍可使用。以下是 iOS 和 Android 的设置方法：

iOS：
- 安装 Obsidian 应用。
- 方法一：直接使用 Git 插件：
  - 在 Obsidian 设置中安装 Git 插件，配置与桌面端相同（输入 PAT）。
  - 克隆仓库：进入插件设置，选择 Clone an existing remote repo，输入仓库 HTTPS 地址和 PAT。
  - 限制：大仓库可能较慢，建议关闭 Auto commit，手动触发同步。
- 方法二：使用第三方 Git 客户端（如 Working Copy）：
  - 安装 Working Copy（需付费，约 $19.99）。
  - 在 Working Copy 中克隆 GitHub 仓库。
  - 在 Obsidian 中打开 Working Copy 的文件夹作为 Vault。
  - 使用 Working Copy 手动提交和推送更改。
Android：
- 安装 Obsidian 和 Termux（终端模拟器）。
- 在 Termux 中安装 Git（pkg install git），然后克隆仓库。
- 在 Obsidian 中打开克隆的文件夹。
- 配置 Git 插件或通过 Termux 手动执行 Git 命令。
注意事项：
- 移动端同步可能较慢，尤其是文件较多时。
- 建议在移动端只做轻量编辑，复杂操作留给桌面端。

高级设置（可选）

使用 SSH 认证：
- 将公钥（~/.ssh/id_ed25519.pub）添加到 GitHub（Settings > SSH and GPG keys > New SSH key）。
- 好处：无需每次输入 PAT，适合频繁推送。
处理冲突：
- 如果多设备同时编辑同一文件，可能出现合并冲突。
- 解决方法：
  - 打开终端，运行 git pull 查看冲突。
  - 手动编辑冲突文件，选择保留的更改。
  - 提交修复：git add . && git commit -m "Resolve conflict" && git push。
- 预防：设置较短的自动拉取间隔，避免同时编辑。
优化大仓库：
- 如果 Vault 文件较多，启用插件的 Stage files individually 选项。
- 定期清理 .gitignore 中的无关文件。
- 考虑使用 LFS（Large File Storage）存储大附件（需额外配置）。

更新远程仓库地址为 SSH：

git remote set-url origin [email protected]:你的用户名/Obsidian-Notes.git

生成 SSH 密钥：

ssh-keygen -t ed25519 -C"[email protected]"

注意事项

隐私保护：
- 确保仓库为私有，防止笔记泄露。
- 不要将 PAT 存储在 Vault 中，建议使用密码管理器。
备份：
- GitHub 不是真正的备份解决方案，建议定期导出 Vault 到本地或其他云服务（如 Google Drive）。
性能问题：
- 如果 Vault 包含数千个文件，同步可能变慢。尽量精简 Vault，移除不必要的文件。
移动端限制：
- Obsidian Git 在移动端可能不稳定，建议主要在桌面端操作。
学习曲线：
- 如果你是 Git 新手，可能需要时间适应术语（如 commit、push、pull）。遇到问题时，查阅 GitHub 文档或 Obsidian 论坛。

故障排除

推送失败（401/403 错误）：
- 检查 PAT 是否正确或已过期。
- 确认 PAT 有 repo 或 Contents 权限。
插件没有自动提交：
- 确保 Vault backup interval 已设置。
- 检查终端是否有 Git 错误（运行 git status 查看状态）。
同步冲突：
- 运行 git pull --rebase 尝试自动合并。
- 如果失败，手动解决冲突（见“高级设置”）。
移动端卡顿：
- 禁用移动端的自动提交，手动触发同步。
- 考虑使用第三方 Git 客户端。