尧图网站建设 免费方案咨询
ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

首页/资讯中心/资讯详情

基于Git的Obsidian笔记免费同步方案：从原理到实践

发布时间：2026/8/9 10:10:47 尧图网站建设
基于Git的Obsidian笔记免费同步方案：从原理到实践

1. 项目概述：为什么我们需要一个免费的 Obsidian 同步方案？

如果你和我一样，是一个重度依赖 Obsidian 进行知识管理和写作的人，那么“同步”这个问题，大概率是你心头的一根刺。Obsidian 官方推出的 Sync 服务，功能固然稳定强大，但每月几十元的订阅费，对于个人用户，尤其是学生或笔记量不大的用户来说，长期来看也是一笔不小的开销。更关键的是，我们的笔记数据往往非常私密，将它们完全托管在云端服务上，心里总有些不踏实。

于是，寻找一个免费、安全且可控的同步方案，就成了很多 Obsidian 玩家的刚需。Git，这个程序员们再熟悉不过的版本控制工具，自然就进入了视野。它天生就是为了管理文件变更而生的，每一次修改都有记录，可以轻松回滚到任意历史版本，还能在不同设备间同步。但 Git 本身的使用门槛，以及需要搭配 GitHub、Gitee 等代码托管平台，对于非技术背景的用户来说，配置过程显得有些晦涩难懂。

而“Hermes Agent LLM Wiki”这个项目的出现，恰好为这个痛点提供了一个优雅的解决方案。它本质上是一个智能的本地知识库助手，能够理解你的笔记内容，并进行智能问答和检索。但更重要的是，它项目结构中倡导的“Git 同步”工作流，为我们提供了一套现成的、经过验证的配置范式。我们不需要从零开始研究如何用 Git 同步 Obsidian 仓库，而是可以直接参考甚至复用这个成熟项目的配置。

所以，这篇教程的核心目的，就是手把手带你走通这条路：利用 Git 和参考 Hermes Agent LLM Wiki 的实践，为你的 Obsidian 笔记库搭建一个完全免费、自主可控的同步系统。无论你是在 Windows、macOS 还是 Linux 上，无论你之前是否接触过 Git，跟着步骤走，都能搞定。

2. 核心思路与方案选型：Git 同步的底层逻辑

在动手之前，我们必须先理解这套方案的核心思路。这不仅仅是点几下鼠标，更是理解一种更可靠的数据管理哲学。

2.1 为什么是 Git，而不是网盘同步？

很多人的第一反应可能是：我用百度网盘、iCloud 或者 Dropbox 同步 Obsidian 的仓库文件夹不就行了吗？确实可以，但这存在几个显著问题：

  1. 冲突处理能力弱：当你在手机和电脑上同时修改了同一篇笔记，网盘通常只会机械地保留最后同步的那个版本，或者生成一堆“冲突副本”，你需要手动合并，非常麻烦。而 Git 能清晰地告诉你哪里发生了冲突，并提供了成熟的合并工具。
  2. 版本历史缺失：网盘虽然可能有“历史版本”功能，但往往有期限、数量限制，且回溯不够直观。Git 的每一次提交（Commit）都是一个完整的快照，你可以随时查看任何时间点的笔记状态，甚至可以轻松对比两个版本之间的具体差异。
  3. 数据安全与隐私：使用国内的 Git 服务（如 Gitee）或自建 Git 服务器，数据完全在可控范围内。而某些网盘服务的隐私条款和数据存储位置可能让你有所顾虑。
  4. 跨平台一致性：Git 是标准工具，在 Windows、macOS、Linux 上行为一致。而不同网盘客户端的同步策略和性能可能差异很大。

Git 同步的本质，是把你的 Obsidian 笔记库变成一个代码仓库。你在一台设备上“提交”修改，然后“推送”到远程仓库（如 Gitee）；在另一台设备上“拉取”远程的更新到本地。这个过程精准、可追溯。

2.2 Hermes Agent LLM Wiki 项目给我们的启示

Hermes Agent LLM Wiki 是一个典型的基于本地文档的智能问答项目。它的文档明确指出了使用 Git 进行版本管理和同步。我们从它的项目结构中能学到什么？

  • .gitignore文件：这个文件定义了哪些文件不需要被 Git 跟踪。对于 Obsidian，我们同样需要忽略缓存文件（如.obsidian/workspace）、临时文件以及某些插件生成的数据，避免将无关内容同步上去，也能提升同步速度。我们可以直接参考或复用它的忽略规则。
  • 清晰的提交约定：一个好的 Git 使用习惯是，每次提交都有清晰的信息。Hermes 项目的提交历史通常是“添加功能 X”、“修复问题 Y”、“更新文档 Z”。对于笔记同步，我们也应该养成习惯，比如“更新《读书笔记-深度工作》”、“整理日记 2023-11”、“添加新笔记模板”，这样历史记录一目了然。
  • 分支策略的简化应用：对于个人笔记，我们可能不需要复杂的分支。但理解“主分支（main/master）”保存稳定版本，偶尔可以开一个“草稿分支”来写一些不成熟的想法，写完后合并回去，这是一种非常清爽的内容管理方式。

基于以上思路，我们的方案选型就非常明确了：以 Git 为核心同步工具，以国内访问速度快的 Gitee（码云）作为免费远程仓库，在 Obsidian 中通过命令行或图形化工具完成日常的提交与同步操作。整个方案的成本为 0，且完全自主。

3. 环境准备：安装与配置 Git

这是最基础，也是最重要的一步。我们将以 Windows 平台为例，macOS 和 Linux 用户也可以找到对应的安装方法，核心配置命令是通用的。

3.1 下载与安装 Git

  1. 访问官网：打开 Git 的官方网站，找到下载页面。对于 Windows 用户，直接下载 “Standalone Installer” 即可。
  2. 运行安装程序：双击下载好的.exe文件启动安装向导。
  3. 关键安装选项：
    • 选择组件：保持默认，确保 “Git Bash Here” 和 “Git GUI Here” 被选中，这会在右键菜单添加快捷入口。
    • 选择默认编辑器：推荐选择 “Use Visual Studio Code as Git‘s default editor”，这样在需要输入提交信息时会用 VSCode 打开，比内置的 Vim 友好得多。如果你没有安装 VSCode，可以选择 Notepad++ 或其他你熟悉的编辑器。
    • 调整 PATH 环境：选择“Git from the command line and also from 3rd-party software”。这是最关键的一步，它会把 Git 添加到系统的 PATH 环境变量中，让你可以在任何命令行窗口（如 CMD、PowerShell）中直接使用git命令。
    • 选择 HTTPS 传输后端：选择 “Use the OpenSSL library”。
    • 配置行尾转换：选择“Checkout Windows-style, commit Unix-style line endings”。这个选项能最好地处理 Windows 和 macOS/Linux 之间换行符的差异，避免出现大量不必要的修改提示。
    • 选择终端模拟器：选择 “Use MinTTY”，这是 Git Bash 的默认终端，体验更好。
    • 其他选项：剩余选项如 “Enable file system caching”、 “Enable Git Credential Manager” 都保持默认推荐即可。

注意：行尾符配置是跨平台同步笔记时的一个经典坑。如果配置不当，你可能会发现明明没改内容，Git 却提示整个文件都被修改了。上述选择能最大程度避免这个问题。

  1. 点击 “Install” 完成安装。

3.2 初始全局配置

安装完成后，在开始菜单找到 “Git” -> “Git Bash”，打开一个黑底绿字的命令行窗口。我们需要进行一些基本的全局配置，这些配置只需要做一次。

# 配置你的用户名和邮箱，这将会记录在你的每一次提交中 git config --global user.name "你的名字或昵称" git config --global user.email "你的邮箱地址" # 让 Git 命令输出带颜色，更容易阅读 git config --global color.ui auto # 设置默认分支名为 main（现代 Git 的推荐做法） git config --global init.defaultBranch main # 检查配置是否成功 git config --global --list

请务必将上面的你的名字或昵称和你的邮箱地址替换成你自己的信息。这个邮箱最好与你后续注册 Gitee 或 GitHub 的邮箱一致。

实操心得：很多人会随便填一个邮箱，这没问题。但如果你未来某天想将这个仓库公开，或者参与开源项目，这个身份信息就会变得重要。建议使用一个常用的、真实的邮箱。

4. 创建远程仓库与本地初始化

我们需要一个“云端保险箱”来存放笔记。这里选择 Gitee，因为它在国内访问速度快且稳定。

4.1 在 Gitee 上创建新仓库

  1. 注册并登录 Gitee。
  2. 点击页面右上角的 “+” 号，选择 “新建仓库”。
  3. 填写仓库信息：
    • 仓库名称：例如my-obsidian-notes。起一个容易识别的名字。
    • 路径：会自动填充，一般和仓库名一致。
    • 介绍：可选，填写“我的 Obsidian 笔记同步仓库”。
    • 仓库类型：选择“私有”。这是最重要的！你的笔记很可能包含个人隐私，务必设为私有。
    • 其他选项：
      • 不勾选“使用 Readme 文件初始化这个仓库”。因为我们打算从一个已有的本地文件夹初始化。
      • 不勾选“选择模型”。保持空白。
      • 在 “.gitignore” 模板中，可以选择Node.js或直接留空，我们后面会自己配置更精确的。
      • 在 “开源许可证” 中，选择 “不指定”。
  4. 点击“创建”按钮。

创建成功后，你会看到一个空仓库的页面，页面上会显示仓库的 HTTPS 地址，格式如https://gitee.com/你的用户名/my-obsidian-notes.git。复制这个地址，稍后会用到。

4.2 初始化本地 Obsidian 仓库

现在，我们回到你的电脑，对你现有的 Obsidian 笔记库（Vault）进行操作。如果你还没有笔记库，先在 Obsidian 里创建一个。

  1. 打开你的 Obsidian 笔记库所在的文件夹。你可以在 Obsidian 左下角点击“打开其他仓库”，查看当前仓库的路径。
  2. 在这个文件夹的空白处，右键单击，选择 “Git Bash Here”。这会直接打开一个 Git Bash 终端，并且工作路径就在你的笔记库根目录。
  3. 在 Git Bash 中，依次执行以下命令：
# 1. 初始化本地 Git 仓库 git init # 2. 将本地仓库与远程的 Gitee 仓库关联起来 # 将下面的 URL 替换成你刚刚复制的 Gitee 仓库地址 git remote add origin https://gitee.com/你的用户名/my-obsidian-notes.git # 3. 创建并配置 .gitignore 文件 # 这个文件告诉 Git 哪些文件不需要跟踪。我们先创建一个基础版本。 echo -e ".obsidian/workspace*\n.trash/\n*.tmp\n.DS_Store\nThumbs.db" > .gitignore

让我们解释一下.gitignore文件里的内容：

  • .obsidian/workspace*：忽略 Obsidian 的窗口布局、打开文件状态等缓存信息，这些是纯本地偏好，不需要同步。
  • .trash/：忽略 Obsidian 的回收站文件夹。
  • *.tmp：忽略所有临时文件。
  • .DS_Store：macOS 系统生成的文件夹元数据文件。
  • Thumbs.db：Windows 系统生成的缩略图缓存文件。

注意事项：.obsidian文件夹本身是需要同步的！因为它里面包含了你的核心配置、插件、主题和自定义片段。我们只忽略其中的workspace等动态缓存文件。你可以用文本编辑器打开.gitignore文件，根据实际情况增删规则。

5. 核心同步流程实操

环境搭好了，仓库联通了，接下来就是日常使用的核心操作。我们将模拟一个完整的“在电脑A上写笔记，然后在电脑B上获取更新”的工作流。

5.1 日常提交与推送（在电脑A上操作）

假设你刚在电脑A上写完或修改了一些笔记。

  1. 打开 Git Bash：在你的 Obsidian 仓库根目录右键，打开 “Git Bash Here”。
  2. 检查状态：首先，用git status命令看看哪些文件被修改、新增或删除了。这会给你一个清晰的概览。
    git status
    你会看到红色的文件名，表示这些是已修改但未暂存（未准备提交）的文件。
  3. 添加变更到暂存区：你可以添加所有变更，也可以添加特定文件。
    # 添加所有变更（最常用） git add . # 或者只添加特定文件 git add 日记/2023-11-01.md 读书笔记/深度工作.md
    执行git add .后，再运行git status，你会看到文件名变成了绿色，表示它们已进入暂存区，等待被提交。
  4. 提交变更：给这次提交写一个清晰的说明信息。
    git commit -m "更新：完成《深度工作》读书笔记第三章；新增11月日记模板"
    -m后面的字符串就是提交信息。养成写清晰提交信息的习惯，未来的你会感谢现在的自己。
  5. 推送到远程仓库（Gitee）：
    git push -u origin main
    第一次推送时需要使用-u参数，它将本地main分支与远程origin仓库的main分支关联起来。以后再次推送，只需要简单的git push即可。 这时，Git Bash 会弹出一个窗口，让你输入 Gitee 的用户名和密码（或令牌）。输入后，你的本地提交就被上传到 Gitee 的私有仓库了。

5.2 在另一台设备（电脑B）上克隆与拉取

现在，换到电脑B，你想继续工作。

  1. 安装并配置 Git：重复第3部分的步骤，在电脑B上安装 Git 并进行同样的全局配置（用户名和邮箱）。
  2. 克隆远程仓库：这不是打开一个现有文件夹，而是“下载”整个仓库。
    • 在电脑B上找一个合适的位置（比如D:\Notes或~/Documents）。
    • 在此处打开 Git Bash。
    • 运行克隆命令（URL 还是你那个仓库地址）：
      git clone https://gitee.com/你的用户名/my-obsidian-notes.git
    • 命令执行后，会生成一个my-obsidian-notes文件夹，里面就是你所有的笔记和.obsidian配置。
  3. 用 Obsidian 打开这个仓库：打开 Obsidian，选择“打开文件夹为仓库”，然后选择刚刚克隆下来的my-obsidian-notes文件夹。你会发现，你的笔记、插件、主题甚至设置都一模一样地过来了！
  4. 日常拉取更新：当你在电脑A上又推送了新的修改后，在电脑B上，只需要在仓库目录打开 Git Bash，执行：
    git pull
    这个命令会自动从 Gitee 拉取最新的变更并合并到你的本地。然后你在 Obsidian 里刷新一下，就能看到最新的内容。

5.3 处理冲突：当两台电脑同时修改了同一行

这是 Git 同步中最需要小心的情况，但处理起来并不难。

场景：你在电脑A上修改了“购物清单.md”的第一行，提交并推送了。与此同时，你在电脑B上（还没执行git pull）也修改了同一文件的第一行，然后尝试提交。

会发生什么？

  1. 在电脑B上，你先执行git pull想获取最新更新。
  2. Git 会告诉你：CONFLICT (content): Merge conflict in 购物清单.md。
  3. 用文本编辑器或 Obsidian 打开这个文件，你会看到类似这样的标记：
    <<<<<<< HEAD 电脑B上修改的内容 ======= 电脑A上修改的内容 >>>>>>> commit-id-from-remote
    <<<<<<< HEAD和=======之间是你本地（电脑B）的修改，=======和>>>>>>>之间是远程（电脑A）的修改。

如何解决？

  1. 手动编辑文件：打开冲突文件，仔细看两处修改，决定是保留其中一个，还是将两者合并。删除<<<<<<< HEAD，=======，>>>>>>> commit-id-from-remote这些标记行，并整理成你最终想要的内容。
    # 例如，合并后的内容 电脑A和电脑B修改合并后的新内容
  2. 标记冲突已解决：保存文件后，回到 Git Bash。
    # 将解决冲突后的文件添加到暂存区 git add 购物清单.md # 完成合并提交 git commit -m “解决合并冲突：购物清单.md”
  3. 推送合并结果：
    git push
    现在，远程仓库就包含了合并后的正确版本。

避坑技巧：养成好习惯，在开始写一篇笔记前，尤其是可能在其他设备上打开过的笔记，先执行一次git pull确保本地是最新版本，可以极大减少冲突概率。

6. 进阶配置与自动化

基础流程跑通后，我们可以追求更优雅、更自动化的体验。

6.1 使用 SSH 密钥替代密码认证

每次push都要输密码很麻烦，配置 SSH 密钥可以实现免密操作，也更安全。

  1. 生成 SSH 密钥对（在任意一台电脑上操作一次即可）：
    ssh-keygen -t ed25519 -C “你的邮箱地址”
    连续按回车，接受默认保存路径和不设置密码（或为了安全设置一个密码）。
  2. 查看并复制公钥：
    cat ~/.ssh/id_ed25519.pub
    复制终端输出的全部内容，从ssh-ed25519开始到邮箱结束。
  3. 在 Gitee 上添加公钥：
    • 登录 Gitee，点击头像 -> 设置 -> SSH 公钥。
    • 标题栏随便填，如 “My Laptop”。
    • 将复制的公钥粘贴到“公钥”栏。
    • 点击“确定”。
  4. 测试连接：
    ssh -T git@gitee.com
    如果看到 “Hi XXX! You‘ve successfully authenticated...” 的欢迎信息，说明成功。
  5. 修改远程仓库地址为 SSH 协议：
    # 先查看当前的远程地址 git remote -v # 如果是 https 开头，将其改为 ssh 地址 git remote set-url origin git@gitee.com:你的用户名/my-obsidian-notes.git
    之后再进行git push就不再需要输入密码了。

6.2 在 Obsidian 中集成 Git 操作（可选）

虽然命令行很强大，但如果你希望在 Obsidian 界面内点点按钮就完成同步，可以借助插件。

  1. 安装 “Obsidian Git” 插件：
    • 在 Obsidian 中，打开“设置” -> “社区插件” -> “浏览”，搜索 “Obsidian Git”。
    • 安装并启用它。
  2. 基本配置：
    • 启用插件后，在设置中会出现 “Obsidian Git” 的选项。
    • 你可以设置自动拉取的间隔（如每分钟）、自动提交的间隔（谨慎使用）、提交信息模板等。
    • 左侧边栏会出现一个 Git 图标（通常是分支形状），点击它可以快速执行Pull，Commit，Push等操作，并查看文件状态。

个人建议：对于新手，我强烈建议先熟练使用命令行一段时间。图形化插件虽然方便，但一旦出现冲突等复杂情况，命令行给你的控制力和清晰度是无可替代的。等你完全理解了流程，再使用插件作为快捷操作辅助。

6.3 优化 .gitignore 文件

一个精准的.gitignore可以保持仓库清洁。以下是针对 Obsidian 的更完整示例：

# Obsidian 缓存和临时文件 .obsidian/workspace* .obsidian/workspaces.json .obsidian/graph.json .obsidian/trash/ .obsidian/core-plugins-migration.json # 操作系统生成的文件 .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db desktop.ini # 编辑器或IDE生成的文件 *.swp *.swo *~ *.log # 特定插件可能生成的不需要同步的数据 # 例如 ‘Dataview’ 的缓存 .obsidian/plugins/dataview/data.json # 例如 ‘Templater’ 的脚本缓存 .obsidian/plugins/templater-obsidian/scripts/.cache/ # 你的笔记中可能包含的附件缓存目录（如果附件是外链或动态生成） assets/.cache/

你可以根据自己安装的插件，查看其文档或观察其生成的文件，将不需要同步的路径添加进来。

7. 常见问题与故障排查实录

即使按照教程一步步来，也可能会遇到一些问题。这里记录了几个我亲自踩过的坑和解决方法。

7.1 问题：执行git push时提示 “Authentication failed”

可能原因与解决：

  1. 密码错误：HTTPS 方式下，Gitee 的密码不是你网站的登录密码，而是账户密码（在设置->安全设置中查看）或者你专门生成的私人令牌。更推荐使用私人令牌。
    • 去 Gitee 设置 -> 安全设置 -> 私人令牌，生成一个具有“仓库”权限的令牌。
    • 在执行git push输入密码时，粘贴这个令牌。
  2. 认证信息缓存错误：Windows 凭据管理器里可能存了旧的、错误的密码。
    • 打开“控制面板” -> “用户账户” -> “管理 Windows 凭据”。
    • 在“普通凭据”里，找到git:https://gitee.com相关的条目，将其删除。
    • 再次执行git push，重新输入正确的密码或令牌。
  3. 未使用 SSH：如果配置了 SSH 但还在用 HTTPS 地址，也会失败。确保git remote -v显示的地址是git@gitee.com:...开头。

7.2 问题：.obsidian文件夹下的插件没同步过去

排查步骤：

  1. 检查.gitignore文件，是否误将整个.obsidian目录忽略了。确保忽略的只是workspace*等特定子项。
  2. 在 Git Bash 中，进入仓库目录，运行：
    git status
    查看.obsidian/plugins/下的插件文件夹是否被显示为未跟踪（红色??）或已修改（红色M）状态。如果没有，说明它们没有被 Git 感知。
  3. 手动添加并提交：
    git add .obsidian/plugins/ git commit -m “添加 Obsidian 插件” git push
  4. 在另一台设备上git pull后，需要重启 Obsidian或点击“重新加载应用程序”，插件才会被加载。

7.3 问题：执行git pull后，Obsidian 里看不到新文件

原因与解决： Obsidian 的文件列表有时不会自动刷新。解决方法很简单：

  • 点击 Obsidian 左侧文件列表上方的刷新按钮（一个循环箭头图标）。
  • 或者直接按Ctrl+R(Cmd+R on Mac) 重新加载整个应用。

7.4 问题：我想回退到某个旧版本

这是 Git 最强大的功能之一。

  1. 查看历史：
    git log --oneline
    这会显示简洁的提交历史，每行前面有一串唯一的提交 ID（如a1b2c3d）。
  2. 回退到指定版本：
    • 软回退：仅移动HEAD指针，不改变工作区文件。相当于“撤销提交，但保留修改”。
      git reset --soft a1b2c3d
    • 混合回退（默认）：移动HEAD指针，并重置暂存区，但不改变工作区文件。修改还在，但需要重新git add。
      git reset a1b2c3d
    • 硬回退（危险！）：彻底回退到那个版本，丢弃之后的所有修改。除非你100%确定，否则不要用。
      git reset --hard a1b2c3d
  3. 如果已经推送了错误的版本：在本地回退后，强制推送到远程（会覆盖远程历史，谨慎操作，确保只有你一个人在用这个仓库）。
    git push -f origin main

7.5 问题：仓库越来越大，同步变慢

优化方法：

  1. 检查大文件：使用工具查找仓库中的大文件。
    git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | grep blob | sort -k3 -n | tail -10
    这个命令会列出最大的10个文件。看看是否有不应该被跟踪的大文件（比如视频、压缩包）。
  2. 从历史中移除大文件（高级操作）：如果错误提交了大文件，可以使用git filter-branch或BFG Repo-Cleaner工具将其从历史中彻底删除。但这会改变所有提交ID，如果其他设备已经克隆了仓库，会比较麻烦。操作前务必备份整个仓库。
  3. 常规维护：Git 会自动进行垃圾回收，你也可以手动触发：
    git gc --aggressive --prune=now

这套基于 Git 的 Obsidian 同步方案，我从两年前开始使用，至今稳定可靠。它不仅仅是一个同步工具，更让我养成了对知识资产进行版本管理的好习惯。每一次清晰的提交信息，都是一次对知识脉络的梳理。当你可以随时回到三个月前某个灵光一现的笔记版本时，那种安全感是任何付费云服务都无法完全给予的。

网站建设 视觉设计 SEO优化
返回列表