首先声明：翻墙连接 github 时，不要启用 TUN 模式，否则会推送失败。
使用 SSH 地址将 Obsidian vault 同步到 GitHub 的完整新手教程。
教程从零开始，所有命令都针对 Windows 用户优化，使用 Git （推荐）或 PowerShell 执行。命令带详细中文注释。
第一部分：生成 SSH 密钥对（电脑上只需做一次，永久有效）
-
安装 Git（如果还没安装）
- 去 https://git-scm.com/download/win 下载并安装 Git for Windows（默认选项即可）。
- 安装后会自带 Git （一个终端工具，像 Linux 命令行）。
-
打开 Git （开始菜单搜索 “Git ” 打开）。
-
生成新的 SSH 密钥（推荐 ed25519 类型，更安全更快）
# 生成 ed25519 类型的 SSH 密钥对 # -C "your_email@example.com" 用你的 GitHub 注册邮箱替换 # 按回车接受默认路径（通常是 C:\Users\你的用户名\.ssh\id_ed25519） ssh-keygen -t ed25519 -C "你的邮箱@xxx.com" # 提示 "Enter passphrase"（可选密码保护）： # - 建议设置一个强密码（每次 push 时需输入，或后面用 agent 记住） # - 或直接回车两次（无密码，方便但稍不安全）执行后会在 C:\Users\你的用户名\.ssh\ 生成：
- id_ed25519 ← 私钥（千万别分享！）
- id_ed25519.pub ← 公钥（要上传到 GitHub）
-
启动 ssh-agent 并添加私钥（让系统记住密钥，避免每次 push 问密码）
# 启动 ssh-agent 服务（Windows 需要这一步） eval $(ssh-agent -s) # 添加你的私钥到 agent（如果设了 passphrase，会提示输入密码） ssh-add ~/.ssh/id_ed25519（如果用 PowerShell，也支持类似命令，但 Git 更稳定。）
-
把公钥复制到剪贴板
# 显示公钥内容，然后手动复制全部（从 ssh-ed25519 开头到邮箱结尾） cat ~/.ssh/id_ed25519.pub | clip # 或者直接 cat ~/.ssh/id_ed25519.pub → 右键选中全部 → 复制 -
登录 GitHub → 添加 SSH 公钥
- 浏览器打开：https://github.com/settings/keys
- 点击 New SSH key 或 Add SSH key
- Title：随便填（比如 “My Windows PC 2026”）
- Key type：Authentication Key（默认）
密钥类型：认证密钥（默认） - Key：粘贴刚才复制的公钥全部内容（一行）
- 点击 Add SSH key（可能要输入 GitHub 密码或 2FA 确认）
-
测试 SSH 连接是否成功（关键一步！）
# 测试 GitHub SSH 连接 # 第一次会问 "Are you sure you want to continue connecting?" → 输入 yes 回车 ssh -T git@github.com看到类似输出就成功：
Hi [你的用户名]! You’ve successfully authenticated, but GitHub does not provide shell access.
嗨 [你的用户名]！你已经成功认证了，但 GitHub 不提供 shell 访问。
第二部分：在 Obsidian vault 中初始化 Git 并用 SSH 地址连接远程假设你的 vault 路径是 D:\Obsidian\MyVault（根据实际情况调整）。 -
打开 Git ，进入 vault 根目录（包含 .md 文件和 .obsidian 的文件夹）
# 进入你的 vault 目录（替换成你的实际路径） cd /d D:\Obsidian\MyVault -
初始化 Git 仓库（如果还没初始化）
# 只在第一次执行：把当前文件夹变成 Git 仓库。完成后自动生成一个隐藏文件夹 (.git) git init -
添加 .gitignore 文件（强烈推荐，避免同步 Obsidian 内部文件导致冲突）
- 在 vault 根目录新建一个笔记，命名为 .gitignore（注意开头点），内容示例：
# Obsidian 工作区/缓存（多设备必忽略） .obsidian/workspace* .obsidian/workspace.json .obsidian/hotkeys.json .obsidian/graph.json .obsidian/cache/ # 系统垃圾 .DS_Store Thumbs.db *.tmp
# 添加 .gitignore 到 Git git add .gitignore - 在 vault 根目录新建一个笔记，命名为 .gitignore（注意开头点），内容示例：
-
第一次提交所有文件
# 添加所有文件（笔记、.gitignore 等） git add . # 提交到本地（第一次提交信息随便写） git commit -m "Initial commit: my Obsidian vault first backup" -
创建 GitHub 空仓库（浏览器操作）
-
Repository name：比如 Obsidian-Vault
-
Description：可选
-
不要 勾选任何初始化选项（README / .gitignore / license）→ 保持完全空
-
点击 Create repository
-
获取 SSH 地址
- 在新仓库页面，点击绿色 Code 按钮
- 切换到 SSH tab
- 复制地址：格式是 git@github.com:你的用户名/仓库名.git
示例：git@github.com:markwoochem/Obsindian.git
-
连接远程并推送
# 添加远程仓库（用 SSH 地址！） git remote add origin git@github.com:你的用户名/你的仓库名.git # 重命名分支为 main（GitHub 默认 main） git branch -M main # 第一次推送（-u 设置上游跟踪，以后可直接 git push） git push -u origin main如果提示 passphrase → 输入你设置的 SSH 密码（或如果没有设置，就直接通过）。
第三部分：Obsidian Git 插件设置（自动 commit & push）插件已安装并启用（Obsidian → 设置 → 社区插件 → 搜索 “Git” 安装启用）。进入 Obsidian 设置 → Obsidian Git：
-
Vault backup interval (minutes)：5–10
仓库备份间隔（分钟）：5–10 -
Auto backup after stopping file edits (seconds)：60–120
停止文件编辑后的自动备份（秒数）：60–120 -
Commit and push on auto backup：开启（关键！）
提交并推送自动备份 ： 开启 （关键！） -
Pull changes on startup：开启
启动时拉取更改 ：开启 -
Pull interval (minutes)：5–10
拉取间隔（分钟）：5–10 -
Disable push：关闭（必须！）
关闭推送 ： 关闭 （即是要开启推送！） -
Commit message：{{date}} Windows vault sync（可自定义）
-
Author name for commit / Author email for commit：填你的 GitHub 用户名和邮箱
提交的作者名 / 提交的作者邮箱 ：填你的 GitHub 用户名和邮箱
保存后： -
写笔记 → 停止编辑一会儿 → 插件自动 commit + push（用 SSH，无需每次输入密码）
-
打开 Obsidian → 自动 pull
验证 & 后续 -
浏览器刷新 GitHub 仓库 → 看到文件了吗？
-
改一个笔记 → 等 1–2 分钟 → 看 GitHub 是否更新
-
在 Git 里检查：
git status # 应该显示 “nothing to commit” git remote -v # 看到 origin 是 git@github.com:...（SSH）
如果遇到 “Permission denied (publickey）” → 回到第1部分第7步重测 ssh -T git@github.com。SSH 设置好后，以后所有操作都免密（或只输入 passphrase），非常方便。
可能的问题及解决：——————————————————————————————————————————————
如果github创建新仓库同时添加了README文件或者其他文件，因为版本不同可能会导致推送失败，解决办法（保留远程 + 本地内容）按顺序执行下面命令：
# 1. 先拉取远程的内容（会自动尝试合并）
git pull origin main --allow-unrelated-histories
# - --allow-unrelated-histories 是关键，因为两个仓库历史完全独立
# - 如果出现合并冲突（CONFLICT），Git 会提示哪些文件冲突了
# → 打开那些文件，手动解决冲突（通常保留你想要的部分）
# → 解决完后：git add <冲突文件>，然后 git commit
# 2. 合并/解决完冲突后，再推送
git push origin main
或者更安全一点（推荐新手用）：
git pull origin main --allow-unrelated-histories --rebase
# --rebase 会把你的 commit “挪”到远程 commit 后面，历史更线性好看
# 如果有冲突还是要手动解决，然后 git rebase --continue
git push origin main
如果你确定远程那些文件（比如 README）不需要，直接覆盖（慎用！）
git push origin main --force
# 或简写
git push -f origin main
警告：–force 会把远程仓库里已有的文件/历史完全覆盖掉（比如你加的 README 会被删），只剩你本地这次 commit 的内容。如果是个人仓库且你刚创建、远程只有默认文件，-f 是可以的；但如果别人也 push 过，或者你以后多人协作，千万别乱用 -f。
Comments