Obsidian 加 Git 搭建本地知识库：双向链接与版本控制实战

1. 为什么我最终选择了 Obsidian 加 Git 这套组合

1.1 从笔记越写越乱说起

我用过的笔记软件不算少，从最早的印象笔记，到后来的语雀、Notion，再到本地优先的思源笔记，几乎每一款都深度用过至少三个月。但真正让我停下来、决定长期投入的，是 Obsidian。原因很简单：我的笔记越写越多，但找不回来、连不起来、迁移不出去，这三个问题在云端笔记里始终没有得到根本解决。

Obsidian 的核心逻辑是本地 Markdown 文件加双向链接。你的每一条笔记就是硬盘上一个.md文件，纯文本，任何编辑器都能打开。这一点看起来朴素，但它意味着你对数据的控制权是完整的。软件不做了，文件还在；换电脑了，拷贝文件夹就行；想用其他工具处理，直接读文件即可。这种“数据主权”的感觉，是用过云端笔记被锁定格式之后才能体会到的。

而 Git 的加入，解决的是另一个维度的痛点：版本控制与多端同步。Obsidian 本身不提供同步服务（官方同步要付费），但你的知识库本质上就是一个文件夹，里面全是文本文件。Git 天生就是为管理文本变更而设计的，用它来管理笔记仓库，等于给每一篇笔记都装上了时间机器。哪一天改错了、删多了，一条命令就能回滚。

1.2 这套方案到底适合谁

如果你符合以下任意一条，这套方案值得你花一个周末认真搭起来：

• 笔记量已经超过 500 篇，开始出现“写了但找不到”的情况
• 对数据隐私有要求，不希望笔记内容存在别人的服务器上
• 有多台设备（比如家里台式机加公司笔记本），需要同步但不想付订阅费
• 喜欢折腾、愿意花一点学习成本换取长期的自由度和可控性
• 已经在用 Markdown 写作，或者打算把写作流程统一到 Markdown 上

反过来说，如果你完全不想碰命令行、对“版本控制”四个字有生理性抗拒、或者笔记量还不到 100 篇，那这套方案的学习曲线可能会让你中途放弃。工具是为人服务的，没必要为了折腾而折腾。

1.3 整体架构长什么样

在动手之前，先把整个方案的骨架说清楚。你的知识库就是一个普通文件夹，里面存放所有.md笔记文件和附件（图片、PDF 等）。这个文件夹同时是一个 Git 仓库，每次修改后提交一次，就形成了一个版本快照。多端同步通过远程仓库（比如 Gitee 或 GitHub 的私有仓库）中转：A 电脑提交推送，B 电脑拉取合并。

Obsidian 负责编辑和链接，Git 负责版本和同步，Markdown 负责格式，三者各司其职。Obsidian 社区有一个 Git 插件，可以把提交、推送、拉取这些操作集成到软件界面里，不用每次都切到命令行。但我的建议是：前期先老老实实用命令行把 Git 的基本操作跑熟，再上插件。否则出了问题你连排查的方向都没有。

2. 环境搭建：从下载到第一次提交

2.1 Obsidian 的安装与初始配置

Obsidian 官网下载安装包，Windows 和 macOS 都有对应版本。有朋友反馈下载速度慢，这是网络环境问题，多试几次或者换个时间段通常能解决。安装过程没什么好说的，一路下一步即可。

首次打开会让你创建或打开一个仓库（Vault）。这里有个关键决策：仓库放在哪里。我的建议是放在一个路径简短、不含中文和空格的目录下，比如D:/KnowledgeBase或~/Documents/MyVault。原因后面讲 Git 的时候会说到，路径里的空格和中文在某些 Git 操作中会引发莫名其妙的报错，一开始就避开能省很多事。

创建完仓库后，Obsidian 会自动生成一个.obsidian隐藏文件夹，里面存放你的插件配置、主题、快捷键等。这个文件夹也要纳入 Git 管理，这样换电脑时所有配置都能同步过去，不用重新设置一遍。

初始配置里我建议先改两个地方：一是开启“严格换行”（Settings → Editor → Strict line breaks），这样 Markdown 里的单个换行会被渲染成<br>，符合中文写作习惯；二是把附件默认路径设置成一个固定文件夹，比如assets，方便统一管理图片。

2.2 Git 的安装与最小化配置

Git 的安装，Windows 用户直接去官网下载安装包，一路默认选项即可。安装完成后在开始菜单里能找到 “Git Bash”，这是一个模拟 Linux 命令行的终端，后面所有 Git 命令都在这里执行。macOS 用户如果装了 Homebrew，一条brew install git就搞定；没装的话，安装 Xcode Command Line Tools 也会自带 Git。

安装完成后，打开 Git Bash，先做两件必须的配置：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两条命令设置的是每次提交时记录的作者信息，不是登录凭证，随便填一个能标识你的名字和邮箱即可。但建议和你后面要用的代码托管平台账号保持一致，方便追溯。

接下来配置一个对中文用户极其重要的选项：

git config --global core.quotepath false

默认情况下，Git 会把中文文件名显示成八进制转义字符，比如\346\226\207\344\273\266.md，根本没法看。关掉这个选项后，中文文件名就能正常显示了。这个坑我踩过，当时以为是文件损坏了，排查了半天。

还有一个可选但强烈建议的配置是设置默认分支名：

git config --global init.defaultBranch main

这样新建仓库时默认分支就是main，而不是老旧的master，和主流平台保持一致。

2.3 初始化仓库与第一次提交

进入你的知识库文件夹，在 Git Bash 里执行：

cd /d/KnowledgeBase git init

第一行命令是切换到你的仓库目录，注意 Git Bash 里的路径写法和 Windows 资源管理器不一样，D:盘要写成/d/。第二行命令会在当前目录创建一个.git隐藏文件夹，这就是版本库的核心，所有历史记录都存在里面。

初始化完成后，先看一下当前状态：

git status

你会看到所有文件都列在 “Untracked files” 下面，意思是 Git 还没有开始跟踪它们。接下来把它们全部加入暂存区：

git add .

这个命令里的点表示“当前目录下所有文件”。执行完再git status，文件会变成绿色，表示已经进入暂存区，等待提交。

然后执行第一次提交：

git commit -m "初始化知识库"

引号里的内容是提交说明，写清楚这次提交做了什么。第一次提交完成后，你的知识库就有了第一个版本快照。以后任何时候想回到这个状态，都可以通过 Git 找回。

注意：.obsidian文件夹里有一些工作区状态文件（比如workspace.json），记录的是你当前打开了哪些标签页、光标在哪一行。这些文件每次关闭软件都会变，纳入版本控制会产生大量无意义的提交。建议在仓库根目录创建一个.gitignore文件，把这些易变文件排除掉。

3. 核心机制拆解：双向链接与版本控制如何协同

3.1 双向链接不只是“跳转”

很多人第一次接触 Obsidian 的双向链接，以为它就是个高级版的书签功能，点一下能跳到另一篇笔记。这个理解太浅了。双向链接的真正价值在于：它让笔记之间形成了网络结构，而不是传统的树状文件夹结构。

传统笔记软件里，一篇笔记只能属于一个文件夹。你把它放在“工作”下面，就找不到它和“学习”的关联。但现实中一个概念往往横跨多个领域。双向链接解决的就是这个问题：你可以在任意笔记里用[[笔记名]]的语法引用另一篇笔记，被引用的笔记会自动记录“有哪些笔记引用了我”。

这个机制带来的直接好处是：你不需要在写笔记之前就想好分类体系。先写，写到哪算哪，用链接把相关的概念串起来。时间长了，Obsidian 的图谱视图会把你笔记之间的关联可视化出来，你会发现自己思考的脉络和知识之间的隐藏连接。

3.2 Git 如何管理笔记的“生长”

知识库是“生长”出来的，不是“规划”出来的。这意味着你的笔记结构会不断变化：今天新建一个文件夹，明天觉得不合适又拆掉；这篇笔记改了十几版，那篇笔记合并到了另一篇里。如果没有版本控制，这些变更都是不可逆的，改错了只能凭记忆恢复。

Git 的提交机制恰好匹配这种生长模式。每次你觉得“这个阶段的工作告一段落了”，就提交一次。提交说明写清楚这次做了什么调整。几个月后回头看提交历史，你能清晰地看到自己的知识体系是如何一步步演化过来的。这本身就是一种元认知的训练。

更重要的是，Git 的分支功能可以让你安全地做实验。比如你想大规模重构笔记的标签体系，但又怕改乱了回不去，可以新建一个分支来操作。改好了合并回主分支，改砸了直接删掉分支，主分支毫发无损。这种“无成本试错”的能力，是纯文件夹管理永远给不了的。

3.3 Markdown 作为底层格式的长期价值

Markdown 的语法简单到十分钟就能学会，但它的生命力在于通用性。你写的.md文件，可以用 Obsidian 打开，可以用 VS Code 打开，可以粘贴到任何支持 Markdown 的博客平台，可以转换成 Word、PDF、HTML。它不绑定任何一家公司，不依赖任何一款软件。

我特别想说的是 Markdown 的表格和图片处理。表格用|和-就能画出来，虽然对齐方式需要记一下语法（:在左边表示左对齐，两边都有表示居中，右边表示右对齐），但写习惯了比在 Word 里拖表格高效得多。图片用![描述](路径)的语法插入，路径可以是相对路径也可以是绝对路径。在 Obsidian 里，我建议统一用相对路径，并且把图片集中放在assets文件夹里，这样整个仓库迁移到任何地方都不会出现图片丢失的问题。

Markdown 的换行是另一个新手容易困惑的点。在标准 Markdown 里，单个换行不会产生新段落，需要空一行才行。但 Obsidian 的“严格换行”选项开启后，单个换行就会被渲染成换行。这个设置对中文用户特别友好，因为我们写作时习惯每段只空一行，段内换行很常见。

4. 多端同步实战：远程仓库的搭建与日常操作

4.1 选择代码托管平台

远程仓库的作用是充当多台设备之间的中转站。国内用户我推荐 Gitee，访问速度快，私有仓库免费。GitHub 也可以，但国内访问偶尔不稳定，同步时可能会失败。两者操作逻辑完全一样，选哪个看你的网络情况。

注册账号后，创建一个新的私有仓库。仓库名随便起，比如knowledge-base。创建时不要勾选“初始化仓库”，因为我们要推送的是本地已有的仓库，远程仓库保持空白即可。

创建完成后，平台会给你一个仓库地址，形如https://gitee.com/你的用户名/knowledge-base.git。这个地址后面会用到。

4.2 配置 SSH 密钥（推荐方式）

连接远程仓库有两种方式：HTTPS 和 SSH。HTTPS 每次推送都要输入账号密码，很麻烦。SSH 配置一次密钥，以后就不用再认证了。虽然初次配置稍微复杂一点，但一劳永逸。

在 Git Bash 里执行：

ssh-keygen -t rsa -b 4096 -C "你的邮箱"

一路回车，会在~/.ssh/目录下生成两个文件：id_rsa是私钥，绝对不能泄露；id_rsa.pub是公钥，需要复制到代码托管平台。

用以下命令查看公钥内容：

cat ~/.ssh/id_rsa.pub

复制输出的全部内容，粘贴到 Gitee 或 GitHub 的 SSH 密钥设置页面。添加完成后，在 Git Bash 里测试连接：

ssh -T git@gitee.com

如果看到欢迎信息，说明配置成功。

4.3 关联远程仓库并首次推送

回到你的知识库目录，执行：

git remote add origin git@gitee.com:你的用户名/knowledge-base.git git push -u origin main

第一行命令把远程仓库地址关联到本地的origin这个名字上。第二行命令把本地main分支推送到远程，-u参数的作用是记住这个关联，以后直接git push就行，不用再指定远程和分支。

推送成功后，刷新 Gitee 页面，你应该能看到所有笔记文件都出现在仓库里了。

4.4 日常同步的完整流程

在多台设备之间同步，核心就是三个动作：拉取、提交、推送。我习惯的流程是这样的：

每天开始工作前，先拉取远程的最新变更：

git pull

然后正常使用 Obsidian 写笔记。写到一个阶段，比如中午休息前或下班前，提交一次：

git add . git commit -m "今日笔记更新" git push

这里有一个关键点：git add .会把所有变更加入暂存区，包括你新建的、修改的、删除的文件。但如果你在.gitignore里排除了某些文件，它们不会被加入。提交说明尽量写具体一点，比如“新增读书笔记三篇，重构标签体系”，方便以后回溯。

在另一台设备上，同样先git pull拉取最新版本，再开始写。如果两台设备同时改了同一篇笔记，Git 会提示冲突，需要手动解决。这种情况在单人使用中不常见，但偶尔会遇到。解决冲突的方法后面会讲。

提示：Obsidian 的 Git 插件可以自动化上述流程。安装插件后，可以设置定时自动提交和推送，比如每 30 分钟一次。但自动提交会产生大量琐碎的提交记录，我个人的做法是手动提交，保持提交历史的清晰。

5. 避坑指南与常见问题排查

5.1 中文文件名与路径问题

前面提到过core.quotepath的配置，这里再强调一次。如果你在git status里看到类似\346\226\207\344\273\266.md的输出，说明这个配置没生效。检查一下是否执行了git config --global core.quotepath false，执行后需要重新打开 Git Bash 才生效。

另外，仓库路径里不要有空格和特殊字符。我见过有人把仓库放在D:/My Notes/知识库这样的路径下，结果 Git 命令各种报错。改成D:/MyNotes/KnowledgeBase就一切正常了。路径问题是最容易被忽视、又最容易引发诡异错误的坑。

5.2 图片管理的最佳实践

Obsidian 默认会把粘贴的图片放在仓库根目录，时间长了根目录会变得很乱。建议在设置里把附件路径改为assets文件夹，并且选择“相对路径”模式。这样图片引用会写成![](assets/图片名.png)，整个仓库迁移时图片不会丢失。

还有一个细节：Obsidian 粘贴图片时会自动生成一个很长的文件名，比如Pasted image 20240101120000.png。这些文件名没有意义，建议安装一个重命名插件，自动把图片名改成笔记名加序号，方便管理和搜索。

Git 对二进制文件（图片就是二进制文件）的版本控制效率不高，每次修改图片都会产生一个完整的新版本，仓库体积会快速增长。如果图片很多，可以考虑用图床，但图床又引入了外部依赖。我的做法是：截图和临时图片放assets里，重要的图表和思维导图用 Excalidraw 插件画，它生成的是 SVG 或 Markdown 格式，Git 管理起来效率高得多。

5.3 合并冲突的处理方法

虽然单人使用很少遇到冲突，但如果你在两台设备上都改了同一篇笔记并且都提交了，拉取时就会冲突。Git 会在冲突文件里插入类似这样的标记：

<<<<<<< HEAD 你本地的内容 ======= 远程的内容 >>>>>>> origin/main

你需要手动决定保留哪部分，删掉标记符号，然后重新git add和git commit。处理冲突的关键是不要慌，仔细对比两边的差异，通常只是格式调整或补充内容，合并起来不难。

预防冲突的最好方法是养成“先拉后写”的习惯。每次打开电脑准备写笔记之前，先git pull一下，确保本地是最新的。这样冲突的概率会大大降低。

5.4 常见问题速查表

5.5 几个提升效率的实操技巧

第一个技巧是关于git commit --amend的。如果你刚提交完发现漏了一个文件，或者提交说明写错了，不用重新提交一次。先git add漏掉的文件，然后执行git commit --amend，它会把你这次的修改合并到上一次提交里，同时可以修改提交说明。这个命令在整理提交历史时非常有用，但注意只对最近一次提交有效，而且如果已经推送到远程，修改后需要强制推送，单人仓库无所谓，多人协作要谨慎。

第二个技巧是关于git worktree的。如果你同时想维护两个版本的笔记（比如一个稳定版、一个实验版），但又不想复制整个仓库，可以用git worktree在同一个仓库上检出两个不同的分支到两个文件夹。这样两个文件夹共享同一个.git历史，节省空间，切换也方便。不过这个功能对新手来说有点超前，知道有这么回事就行。

第三个技巧是关于 Markdown 写作效率的。VS Code 配合 Markdown All in One 插件，可以提供快捷键加粗、斜体、插入链接、生成目录等功能。我有时候会用 VS Code 批量处理笔记，比如批量替换标签、批量重命名文件，比在 Obsidian 里一个个操作快得多。两个工具配合使用，各取所长。

6. 知识库的长期维护与扩展思路

6.1 定期整理与重构

知识库用久了，一定会出现重复笔记、过时内容、断掉的链接。我每个月会花一个小时做一次“仓库体检”：用 Obsidian 的“未链接提及”功能找出应该链接但没链接的笔记，用“孤立笔记”功能找出没有任何链接指向的笔记，决定是删除还是补充链接。

Git 的提交历史在这里发挥了作用。当我犹豫某篇笔记是否还有价值时，会看一下它的修改历史。如果最后一次修改是两年前，而且之后再没被引用过，那大概率可以归档了。归档不是删除，而是移到一个archive文件夹里，保留在仓库中但不参与日常检索。

6.2 与其他工具的联动

Obsidian 的插件生态是它最大的优势之一。我常用的几个联动场景：

Zotero 和 Obsidian 的联动，通过插件可以把文献笔记和引用直接导入 Obsidian，写论文时引用文献非常方便。Jupyter Notebook 的笔记可以导出为 Markdown 后放入知识库，代码和文字说明在一起，回顾时一目了然。甚至可以用 Codex 之类的工具读取 Obsidian 仓库，让 AI 基于你的笔记内容回答问题，这相当于用你自己的知识训练了一个专属助手。

这些联动的前提都是：你的笔记是纯文本的 Markdown 文件，放在一个标准的文件夹里。这正是这套方案的核心价值——数据格式的通用性带来了无限的工具组合可能。

6.3 备份策略：不要只依赖 Git

Git 是版本控制工具，不是备份工具。虽然远程仓库提供了一定程度的备份，但如果你误删了远程仓库，或者平台账号出了问题，数据还是有丢失风险。我的做法是三层备份：本地仓库一份，远程私有仓库一份，再加一个移动硬盘定期冷备份。

冷备份很简单，就是把整个知识库文件夹拷贝到移动硬盘上，一个月一次。拷贝前先git pull确保是最新版本。这个习惯看起来笨，但关键时刻能救命。我见过太多人把所有数据寄托在一个平台上，平台一出问题就全没了。

6.4 关于“第二大脑”的一点个人体会

工具终究是工具，Obsidian 加 Git 这套组合能帮你管理笔记、追溯历史、多端同步，但它不能替你思考。我见过有人花大量时间折腾插件和主题，笔记却没写几篇。这是本末倒置。

我的建议是：先用最简配置写够 100 篇笔记，再考虑优化工作流。写的过程中你自然会知道哪些功能是真正需要的，哪些是花架子。知识库的价值不在于工具多高级，而在于你往里面投入了多少真实的思考和记录。Git 的提交历史会忠实地记录你的每一次进步，这比任何花哨的功能都更有意义。

最后分享一个我坚持了很久的小习惯：每次提交时，在提交说明里多写一句话，记录当时的状态或想法。比如“整理完项目复盘，思路清晰了很多”或者“今天状态不好，只改了几个错别字”。几个月后翻看提交日志，这些碎片记录拼凑起来，就是你知识生长的真实轨迹。