Obsidian + GitHub 自动同步指南

一份完整的笔记自动化同步与备份方案，告别手动命令行，实现无感多端同步。

一、 准备工作

1. 安装 Git：前往 Git 官网 下载并安装（一路默认即可）。
2. GitHub 账号：确保已有账号并登录 GitHub 网页端。
3. Obsidian 插件：在 Obsidian 的社区插件市场搜索并安装 Git。

二、 云端仓库配置

1. 在 GitHub 点击右上角 + 号，选择 New repository。
2. Repository name：建议填写 Obsidian_Notes。
3. Visibility：强烈建议选 Private（私有）以保护笔记隐私。
4. 不要勾选 "Add a README file"（保持仓库为空，这点很重要）。
5. 点击 Create repository。

三、 本地仓库初始化与关联

在你的 Obsidian 笔记根目录下，右键打开终端（Windows 选 Open Git Bash here，Mac 选新建终端窗口），依次执行以下命令：

# 初始化本地 Git 仓库
git init

# 将所有笔记文件添加到暂存区
git add .

# 提交文件并附带备注
git commit -m "Initial commit"

# 将主分支重命名为 main
git branch -M main

# 关联你在 GitHub 创建的远程仓库 
# 💡 注意：根据你的验证习惯，从以下两种方式中【任选其一】执行即可：
# 👉 方式一：使用 HTTPS 链接（适合大多数情况，最简单） # 推荐人群：使用过VsCode自动同步的用户，系统已经自动配置了 Git 凭据管理器。
git remote add origin https://github.com/你的用户名/Obsidian_Notes.git
# 👉 方式二：使用 SSH 链接（进阶推荐，一劳永逸免密） 
# 推荐人群：已经生成了 SSH 密钥（id_ed25519.pub）并成功添加到 GitHub 的用户。 
git remote add origin git@github.com:你的用户名/Obsidian_Notes.git)

# 将本地笔记推送到云端
git push -u origin main

四、 身份验证配置 (SSH 方案)

💡 提示：配置 SSH 后可以永久免密，无需再处理烦人的 Token 和密码失效问题。

1. 生成密钥

在终端输入以下命令（替换为你的 GitHub 注册邮箱）：

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

连续按三次回车键，提示输入密码（passphrase）时直接留空，确保纯免密。

2. 将公钥添加到 GitHub

运行以下命令查看公钥内容：

cat ~/.ssh/id_ed25519.pub

将终端输出的整段文本复制。前往 GitHub 设置 -> SSH and GPG keys -> New SSH key，粘贴并保存。

3. 切换本地连接为 SSH 通道

在笔记目录的终端下执行：

git remote set-url origin git@github.com:你的用户名/Obsidian_Notes.git

4. 解决网络代理导致的 22 端口被封问题

如果测试连接或推送时报错 Connection closed by remote host，请编辑 ~/.ssh/config 文件强制走 443 端口：

gedit ~/.ssh/config 

写入以下内容：

Host github.com
    Hostname ssh.github.com
    Port 443
    User git

五、 Obsidian 插件自动化设置

在 Obsidian 中启用 Git 插件，进入其设置页面的 Automatic 栏目进行如下配置：

• Auto commit-and-sync interval (minutes)：建议设为 5（每 5 分钟自动备份）。
• Auto commit-and-sync after stopping file edits：开启（非常关键的防干扰功能，停止打字后才备份）。
• Auto pull interval (minutes)：建议设为 5（如果你在多台电脑使用，这能确保你及时拉取最新的笔记）。

六、 排除非必要文件 (.gitignore)

为了避免多台电脑的窗口布局、缓存产生冲突，需要忽略 .obsidian 文件夹的部分内容。

在笔记根目录新建一个名为 .gitignore 的文件，填入想要忽略的内容（例如整个 .obsidian/ 或者仅忽略 workspace.json）。

⚠️ 关键警告：清除已追踪缓存

如果你的 .obsidian 文件夹之前已经推送到过 GitHub，仅仅配置 .gitignore 是不生效的！必须在终端执行以下命令将其从 Git 的追踪账本中划掉：

git rm -r --cached .obsidian
git commit -m "清除 .obsidian 缓存，使其被 ignore 规则接管"
git push origin main

七、 常见问题排查与避坑

1. 提示 Everything up-to-date，但云端没更新

• 原因：本地笔记没有打包。Git 不会自动抓取变更，必须先 add 再 commit。
• 解决：这是纯命令行操作时易犯的错。配置好 Git 插件后，插件会自动执行完整的打包流程。

2. 报错：当前分支与上游分支不同 (Diverged)

• 原因：多端修改导致时间线分叉。
• 解决：
  • 常规合并（推荐）：执行 git pull origin main。
  • 强行覆盖云端（以当前电脑为准）：git push -f origin main。

3. 报错：当前分支名和上游不匹配 (fatal: ... HEAD:main)

• 原因：本地叫 master 或其他名字，云端叫 main。
• 解决：统一改为 main 并重新绑定。

  git branch -M main
  git push -u origin main