Obsidian 是一款强大的本地笔记软件，但原生同步功能需要付费订阅。通过 Git + GitHub 可以实现完全免费、安全可控、跨设备无缝同步，同时还能获得完整的版本历史，误删、改错都能一键回滚。

本教程从环境准备到最终全自动同步，全程图文结合、步骤清晰，新手也能一次成功。

一、前期准备：必备工具与环境

1. 安装 Git（核心依赖）

Git 是实现版本控制的基础工具，Obsidian Git 插件依赖它运行。

• 下载地址：Git 官网

• 安装步骤：全程默认下一步即可，无需修改任何配置，安装完成后会自动配置系统环境变量。

• 验证安装：按 Win+R 输入 cmd 打开命令提示符，输入 git --version，显示版本号即安装成功。

2. 注册 GitHub 账号并创建仓库

GitHub 是免费的代码托管平台，用来存储你的笔记备份。

1. 注册地址：GitHub 官网，用常用邮箱注册账号（建议和后续提交邮箱一致）。

2. 创建仓库：

   • 点击右上角 New 按钮，进入仓库创建页面。

   • Repository name：填写仓库名（如 MyObsidian）。

   • Privacy：选择 Private（私有仓库，仅自己可见，保护笔记隐私）。

   • 不要勾选 Add a README file 和 Add .gitignore，保持仓库为空，点击 Create repository 完成创建。

3. 复制仓库地址：创建完成后，复制仓库的 HTTPS 地址（格式为 https://github.com/你的用户名/仓库名.git），后续会用到。

3. 安装 GitHub Desktop（新手推荐，可视化操作）

对于不熟悉命令行的用户，GitHub Desktop 可以实现可视化同步，避免命令行报错，强烈推荐安装。

• 下载地址：GitHub Desktop 官网

• 安装步骤：全程默认下一步，安装完成后登录你的 GitHub 账号，授权完成即可。

二、Obsidian 本地仓库初始化与配置

1. 安装 Obsidian Git 插件

1. 打开 Obsidian，进入你的笔记库（Vault）。

2. 点击左下角 设置 → 第三方插件 → 关闭安全模式（必须关闭，否则无法安装社区插件）。

3. 点击 浏览，搜索 Git，找到作者 Vinzent (Denis Olehov) 的 Obsidian Git 插件，点击 安装，安装完成后启用插件。

2. 初始化本地 Git 仓库

1. 按 Ctrl+P 打开 Obsidian 命令面板，输入 Git: Initialize a new repo（旧版本为 Initialize repository），点击执行。

2. 执行完成后，右侧会自动打开 Git 源码控制面板，显示笔记库内的所有待提交文件，说明本地仓库初始化成功。

3. 配置提交者身份（解决 Author identity unknown 报错）

这是新手最容易遇到的报错，必须提前配置：

1. 打开 Obsidian 设置 → 第三方插件 → Git → 选项。

2. 找到 Commit author 板块：

   • Author name for commit：填写你的 GitHub 用户名（如 SUGXYZ）。

   • Author email for commit：填写你注册 GitHub 时绑定的邮箱（必须一致，否则提交会被标记为未验证）。

3. 保存设置，重启 Obsidian 生效。

4. 创建 .gitignore 文件（核心避坑，必须做！）

.gitignore 用于过滤不需要同步的本地配置文件，避免多设备同步时出现冲突。

1. 在你的 Obsidian 笔记库根目录（即 .obsidian 文件夹所在的文件夹），新建一个文件，命名为 .gitignore（Windows 系统可命名为 .git.，会自动修正为 .gitignore）。

2. 用记事本打开文件，粘贴以下内容，保存即可：

​
# 忽略 Obsidian 本地配置与插件（多设备冲突根源）
.obsidian/workspace
.obsidian/workspace.json
.obsidian/plugins/
.obsidian/themes/
.obsidian/appearance.json
.obsidian/hotkeys.json
.obsidian/community-plugins.json
.obsidian/core-plugins.json
​
# 系统垃圾文件
.DS_Store
Thumbs.db
desktop.ini
​
# 临时文件与日志
*.tmp
*.log
​
# 发布相关目录（如后续用 GitHub Pages 发布笔记）
docs/
site/

三、绑定 GitHub 远程仓库与首次同步

方法一：GitHub Desktop 可视化同步（新手首选，零命令行）

1. 打开 GitHub Desktop，点击 Add an existing Repository。

2. 选择你的 Obsidian 笔记库根目录（如 D:\002Obsidian\MyObsidian），点击 Add Repository。

3. 在左下角的提交信息框，输入 Initial commit: first backup of obsidian vault，点击 Commit to main 完成本地提交。

4. 点击 Publish repository，在弹出的窗口中，确认仓库名和隐私设置（保持 Private），点击 Publish，完成首次推送。

5. 刷新 GitHub 网页仓库，确认笔记文件已成功上传，同步完成。

方法二：命令行手动绑定（适合熟悉 Git 的用户）

1. 打开你的 Obsidian 笔记库根目录，在地址栏输入 cmd，按回车打开当前路径的命令提示符。

2. 依次执行以下命令（替换为你的仓库地址）：

​
# 1. 绑定远程仓库
git remote add origin https://github.com/你的用户名/MyObsidian.git ​ # 2. 重命名本地分支为 main（适配 GitHub 默认分支） git branch -M main ​ # 3. 首次推送，关联本地与远程分支 git push -u origin main

1. 执行过程中会弹出 GitHub 登录窗口，登录账号授权后，推送完成。

四、Obsidian Git 插件全自动同步配置（一劳永逸）

配置完成后，即可实现「写笔记自动备份、多设备自动同步」，完全无需手动操作。以下是最优配置清单，直接照着设置即可：

1. Automatic（自动同步核心设置）

配置项	推荐值	作用说明
Split timers for automatic commit and sync	关闭	统一10分钟同步周期，避免逻辑混乱
Auto commit-and-sync interval (minutes)	10	每10分钟自动提交+同步所有笔记变更
Auto commit-and-sync after stopping file edits	关闭	按固定周期同步，不依赖编辑停止，更稳定
Auto commit-and-sync after latest commit	关闭	不叠加手动提交时间，避免同步延迟
Auto push interval (minutes)	0	关闭单独推送，用 Push on commit 自动推送
Auto pull interval (minutes)	10	每10分钟自动拉取远程最新笔记
Auto commit-and-sync only staged files	关闭	自动同步所有变更，无需手动暂存
Specify custom commit message on auto commit-and-sync	关闭	用预设模板，无需每次手动输入
Commit message on auto commit-and-sync	vault backup: {{date}} {{time}}	自动生成带时间戳的提交信息，方便追溯
Commit message on manual commit	vault backup: {{date}} {{time}}	手动提交统一模板，保持记录一致

2. Commit message / Pull（提交与拉取策略）

配置项	推荐值	作用说明
{{date}} placeholder format	YYYY-MM-DD HH:mm:ss	时间格式精确到秒，记录更清晰
Merge strategy	Merge	标准合并策略，适配个人笔记场景
Merge strategy on conflicts	None (git default)	冲突时手动处理，避免自动覆盖笔记
Pull on startup	开启	打开 Obsidian 自动拉取最新笔记
Push on commit-and-sync	开启	提交后自动推送到 GitHub，实时备份
Pull on commit-and-sync	开启	同步时先拉取再推送，从根源避免冲突

3. Hunk management（行级变更，新手建议关闭）

配置项	推荐值	作用说明
Signs / Hunk commands	全部关闭	个人笔记无需行级变更控制，减少性能消耗
Line author information	关闭	个人使用无需显示提交者信息
Automatically refresh source control view on file changes	开启	源码面板实时刷新，方便查看变更

4. Miscellaneous（杂项与状态显示）

配置项	推荐值	作用说明
Diff view style	Split	分屏对比变更，直观查看修改内容
Hide notifications for no changes	开启	无变更时不弹通知，减少打扰
Show status bar	开启	右下角显示同步状态，一眼确认同步正常
File menu integration	开启	右键菜单添加 Git 操作，方便手动暂存
Show branch status bar	开启	显示当前分支，避免误操作切错分支
Show the count of modified files in the status bar	开启	状态栏显示变更文件数，实时掌握同步状态

5. Advanced（高级设置）

所有选项保持默认即可，无需修改，仅在特殊场景（如自定义 Git 路径）下调整。

五、日常使用与多设备同步指南

1. 日常同步的3种方式

• 全自动模式（日常推荐）：配置完成后，无需任何手动操作，每10分钟自动提交、拉取、推送，打开软件自动同步最新笔记。

• 手动一键同步（立刻同步）：按 Ctrl+P 打开命令面板，输入 Git: Commit and sync，一键完成全流程同步。

• 可视化同步（排查问题用）：打开 GitHub Desktop，点击 Sync 一键同步，可直观查看所有修改、回滚历史、解决冲突。

2. 多设备同步（手机/另一台电脑）

电脑端（新设备）

1. 新设备安装 Obsidian、Git、GitHub Desktop，登录同一个 GitHub 账号。

2. 打开 GitHub Desktop，克隆 MyObsidian 仓库到本地。

3. 用 Obsidian 打开克隆后的文件夹，按上述配置开启 Obsidian Git 自动同步，即可无缝衔接所有笔记。

手机端（iOS/Android）

1. 手机安装 Obsidian App，安装 Obsidian Git 插件。

2. 按 Ctrl+P（手机端为右上角菜单→命令面板），输入 Git: Clone an existing remote repo，输入仓库地址。

3. 克隆完成后，配置自动同步，实现手机与电脑实时同步。

六、常见问题与报错排查

1. Author identity unknown 报错

原因：未配置提交者身份，Git 无法识别提交者。

解决：在 Obsidian Git 设置中填写 Author name 和 Author email，重启 Obsidian 即可。

2. fatal: branch 'main' does not exist 报错

原因：本地分支未重命名，或在 .obsidian 文件夹内执行命令。

解决：回到笔记库根目录，执行 git branch -M main 重命名分支，再执行推送命令。

3. Connection was reset 网络报错

原因：国内网络访问 GitHub 不稳定，连接被重置。

解决：使用 GitHub Desktop 重试，或配置网络代理；新手推荐用 GitHub Desktop，网络稳定性远高于命令行和插件。

4. 多设备同步冲突

原因：未配置 .gitignore，同步了本地配置文件；或多设备同时修改同一文件。

解决：严格按照教程配置 .gitignore；开启 Pull on commit-and-sync，先拉取再推送；冲突时用 GitHub Desktop 手动合并。

七、方案优势与进阶玩法

1. 方案核心优势

• 完全免费：替代 Obsidian 付费同步，零成本实现跨设备备份。

• 安全可控：私有仓库仅自己可见，笔记数据完全掌握在自己手中。

• 版本回溯：完整的 Git 提交历史，误删、改错可一键回滚，数据零丢失。

• 无限空间：GitHub 私有仓库无空间限制，可存储海量笔记。

2. 进阶玩法：免费发布笔记到 GitHub Pages

如果需要将部分笔记做成公开在线文档，可使用 Quartz 工具，一键将 Obsidian 笔记部署为美观的在线文档站，支持双链、搜索、暗色模式，完全免费，替代 Obsidian 官方 Publish 付费功能。

八、最终验收标准

配置完成后，你应该能实现以下效果：

1. 写笔记后，10分钟内自动同步到 GitHub 仓库，网页可查看最新笔记。

2. 多设备打开 Obsidian，自动拉取最新笔记，无缝跨设备使用。

3. .obsidian 本地配置文件不会同步到 GitHub，多设备无冲突。

4. 右下角状态栏实时显示同步状态，有问题可快速排查。

5. 误删笔记可通过 GitHub 提交历史一键恢复，数据安全有保障。

写在最后

本教程全程实测，从新手视角出发，避开了所有常见坑点，按照步骤操作即可一次成功。如果需要进阶配置（如 GitHub Pages 发布、多仓库管理），可在评论区留言，后续会更新对应教程。

温馨提示：定期检查 GitHub 仓库同步状态，确保笔记备份正常，数据安全第一。

需要我帮你补充Quartz 部署 GitHub Pages 的完整教程，让这篇教程覆盖「同步+发布」全流程吗？

（注：文档部分内容由 AI 生成）