Obsidian 加 Gitee 零成本搭建笔记自动同步方案

我折腾 Obsidian 和 Gitee 这套笔记方案的时间不算短了，从最开始把笔记散落在本地文件夹里，到后来尝试各种网盘、同步工具，最后才定下“Obsidian 做笔记、Gitee 做云端仓库、Git 插件做自动同步”这个组合。很多朋友问过我为什么不用现成的云笔记，或者直接用 Obsidian 官方同步服务，这篇文章就从头聊聊我踩过的坑、做过的取舍，以及一套完整可复用的搭建流程。如果你正好在纠结笔记怎么管理、怎么备份、怎么在多个设备之间保持一致，这篇内容应该能给你一个比较踏实的答案。

先说清楚这套方案能干什么：Obsidian 负责把笔记写成纯文本 Markdown 文件，存放在本地的某个文件夹里；Gitee 作为云端 Git 仓库，保存这些文件的版本历史和远程副本；再通过 Obsidian 社区插件（比如 Obsidian Git）在本地仓库和远程仓库之间自动拉取、提交、推送，实现接近实时的同步效果。适合谁用？适合那些笔记量大、希望数据完全自控、不爱被折腾的、又不想为多设备同步支付年费的人，也适合原本就有代码托管经验、想把“写笔记”也纳入版本管理流程的开发者。整个过程其实不复杂，但涉及的知识点比较零散，我按自己实际操作的顺序，把关键细节一次讲清楚。

1. 为什么我最终选了 Obsidian 加 Gitee 这个组合

1.1 先想清楚笔记工具的核心需求

在决定用什么笔记软件之前，我一直提醒自己一个问题：笔记到底意味着什么？如果只是随手记录待办事项，那手机自带的备忘录就够了；如果是要沉淀长期知识、形成自己的理解体系，那笔记的格式、存储方式、迁移成本就变得非常重要。

Obsidian 吸引我的第一个点是纯本地存储。所有笔记就是一个文件夹里的一堆 .md 文件，没有任何私有格式的封装。这意味着即使有一天 Obsidian 这个软件不维护了，我的笔记依然是普通的文本文件，可以用 Typora、VS Code、甚至系统自带的记事本打开。这种“数据所有权”的踏实感，是很多在线云笔记给不了的。第二个点是双链机制，笔记之间的链接通过[[笔记名]]这种语法实现，可以在脑子里构建出一个知识网络，而不只是按文件夹堆叠的文件。第三个点是插件生态非常丰富，从自动同步、图表展示，到日历、闪卡、AI 辅助，几乎想要什么功能都能找到对应插件。

但随之而来的问题是：纯本地存储怎么保证数据安全？电脑硬盘坏了怎么办？想在办公室的电脑和家里的笔记本之间接续写作怎么办？这就引出了“云存储同步”的需求。市面上其实有很多现成的同步方案，我后面会详细对比，但最终 Gitee 这套组合胜出，是因为它同时解决了备份、历史版本、多端同步三个问题，而且几乎没有额外费用。

1.2 各家同步方案的取舍对比

这里把我在选型阶段认真考虑过的方案摆出来比较一下，方便你对照自己的情况判断。

从表格可以看出，Gitee 最大的优势不是“最容易”，而是“最可控”。Git 本身就是为版本管理设计的，每一次提交都是一次快照，误删、改错都能随时回滚。我一开始也担心配置麻烦，但实际走完一遍流程也就半小时。比起同步到一半出现冲突文件、或者云端服务器抽风导致笔记同步乱掉，这半小时的前期投入非常值得。

2. 开工前的准备清单

2.1 下载安装 Obsidian 与初始配置

第一步自然是把 Obsidian 装好。直接去官网下载对应的安装包，Windows、macOS、Linux 都有对应的版本，手机端也从应用商店找 Obsidian 安装。这里有个小建议：安装路径尽量简单，不要带中文和空格，尤其是 Windows 系统，某些插件对路径的兼容性没那么好，后面跑 Git 命令的时候也会省掉很多转义问题。

装好之后首次启动，Obsidian 会问你要“创建新的库”还是“打开已有库”。我建议先创建一个测试库，随便写两篇笔记熟悉一下界面，等到后面仓库配置好了再正式建库。创建时注意记下你的库文件夹路径，后面所有 Git 操作都在这个路径下进行。

接下来强烈建议你把“设置-编辑器-严格换行”关掉，把“设置-文件与链接-新附件位置”改成“当前文件所在文件夹”。前者影响 Markdown 编辑体验，后者决定了你插入图片等附件时文件会不会乱跑。这些细节不处理，等笔记多了你再来理顺路径，那才叫真的头疼。

2.2 本地 Git 安装与基础环境

Obsidian 本身不会帮你执行 Git 操作，同步这件事需要一个 Git 客户端。Windows 用户直接下载 Git for Windows，安装时一路 Next 即可，但注意在“Adjusting your PATH environment”这一步选择第一项“Git from the command line and also from 3rd-party software”，这样 obsidian-git 插件调用的 shell 才能识别 git 命令。macOS 用户一般系统自带 git，没有的话安装 Xcode Command Line Tools 就行。

装好后打开命令行，依次检查版本和设置全局用户信息：

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

这两条配置会影响每一次提交记录的署名，跟 Gitee 账号邮箱保持一致最好。如果你以后参与其他 Git 项目，这些配置也是通用的。还有一条建议：Windows 用户执行下面的命令，避免因为换行符差异导致 Git 提示“整个文件都被修改了”：

git config --global core.autocrlf true

原理很好理解：Windows 的文本换行是 CRLF，而 Linux/macOS 是 LF，Git 需要一种策略来转换。设成 true 后，提交到远程仓库时自动把 CRLF 转成 LF，拉取下来再转回 CRLF。如果不处理，以后你从 Gitee 克隆仓库到别的电脑上，可能看到 Git 状态里莫名其妙有大量改动。

2.3 生成 SSH 密钥并配置到 Gitee

这一步是整套流程里最容易出错的地方，但它解决了每次推送都要输密码的问题。Git 连接远程仓库有两种常见协议：HTTPS 和 SSH。HTTPS 简单但每次都得输账号密码，二选一可以先凑合用；SSH 则通过密钥对认证，配置好后完全免密。我强烈建议直接用 SSH，一次配置，后面百事无忧。

打开终端，执行：

ssh-keygen -t ed25519 -C "你的邮箱"

一路回车，默认保存位置即可。这样会在用户目录的 .ssh 文件夹下生成一对密钥：id_ed25519 是私钥，千万别泄露；id_ed25519.pub 是公钥，可以给任何 Git 平台。查看公钥内容：

cat ~/.ssh/id_ed25519.pub

复制输出的整段内容，登录 Gitee，进入“设置-安全设置-SSH 公钥”，把内容粘贴进去，起个方便识别的标题，比如家里电脑或公司笔记本。保存后可以验证一下连接：

ssh -T git@gitee.com

看到提示欢迎信息，就说明密钥生效了。我在这里踩过坑：一开始把私钥路径搞错了，插件里配置 SSH 私钥路径总是找不到文件，后来才意识到 Windows 的路径写法要用/c/Users/你的用户名/.ssh/id_ed25519这种正斜杠格式。这个问题后面在常见问题里还会细说。

3. 从零搭建同步仓库

3.1 在 Gitee 创建私有仓库

登录 Gitee，右上角“新建仓库”。仓库名称建议与本地库文件夹同名，方便记忆，比如我的知识库叫 notes，那仓库名也填 notes。路径会自动生成，可以改但没必要。

有三个选项需要认真选。第一个是“仓库类型”，我选私有。笔记这种东西毕竟属于个人数据，虽然大部分内容可能不敏感，但没必要默认公开。第二个是“初始化仓库”，不勾选“使用 Readme 初始化仓库”。因为你本地已经有文件了，远程仓库如果先有了内容，第一次关联时会出现“两个不相关的提交记录”的合并问题，处理起来比较麻烦。第三个是“选择许可证”，如果后续不打算公开分享，随便选一个或保持无都行；万一临时想放开，再按情况添加 LICENSE 文件。关于开源许可证怎么选，Gitee 的通用建议是：你希望别人能自由使用你的代码，就选 MIT；希望别人修改后也必须开源，就选 GPL 3.0。笔记仓库根本不用纠结这些，全部默认跳过即可。

创建完成后，仓库页面上会有一段 HTTPS 和 SSH 的仓库地址。我们要用的是 SSH 那个，形如git@gitee.com:你的用户名/notes.git。记下它，后面要用。

3.2 本地初始化与托管到 Gitee 的完整命令流程

现在切回到本地笔记库文件夹。我以 Windows 命令行为例，先从命令行进入该目录：

cd /d D:\Notes\MyVault

这里注意：路径不要包含中文；如果 Obsidian 打开的库正好是这个文件夹，建议先把 Obsidian 关掉，避免文件写入冲突。接下来初始化仓库：

git init git add . git commit -m "first commit"

git add .的作用是把当前文件夹下所有文件放入暂存区，git commit -m则生成一个提交快照。此时本地仓库已经就绪。接着关联远程仓库并推送：

git remote add origin git@gitee.com:你的用户名/notes.git git branch -M main git push -u origin main

这里为什么要git branch -M main？因为新版 Git 默认分支名是 main，而老版本可能是 master，Gitee 默认分支也可能不是 main，手动统一可以避免推送时报错。-u参数把本地 main 分支的上游绑定到远程 main，以后直接执行git push或git pull就行，不用每次带完整参数。

推送成功后，去 Gitee 仓库页面刷新，应该能看到所有笔记文件了。我的习惯是这一步先确认成功，再进行 Obsidian 插件的自动同步，否则插件配置错了不太好排查。

3.3 使用 Obsidian Git 插件实现自动同步

手动用命令行推送当然也行，但每天都要执行一遍很容易忘。Obsidian Git 插件把这个过程自动化了，这也是整套方案最好用的部分。进入 Obsidian 设置-第三方插件-浏览，搜索“Obsidian Git”，安装并启用。

打开插件设置，有几项必须按自己的节奏设好。每个数字都有实际意义，我给出我使用的配置和理由：

• 自动备份间隔（分钟）：我设 60。太短会频繁提交，产生大量无意义的历史记录；太长则失去了同步的实时性。如果你一天改很多，可以缩短到 30。
• 自动拉取间隔（分钟）：设 20。拉取操作是把远程仓库的新内容拉下来，如果你的多台设备轮流使用，这个值建议等于或小于备份间隔，避免另一台设备刚推送完，这台还没拉到最新版。
• 推送间隔（分钟）：设 30。这个值是设定后，插件会自动帮你推送到远程，如果你分开设置了拉取和推送，那推送间隔略高于拉取即可。
• 一键备份与同步：在左侧功能区添加一个按钮，点击后会依次执行拉取、提交、推送全链路。强烈建议开启，手动控制更稳。

这里提一下文件变更的自动提交逻辑：插件会监控 .obsidian 配置目录的变化。也就是说，你平时在 Obsidian 里改了主题、装了插件、改了快捷键，这些配置变更也会被自动提交。这样换新电脑克隆仓库后，连 Obsidian 的外观和插件配置都能一并带过来，这是网盘同步做不到的一点。

首次启用插件后，建议先手动点一次“一键备份与同步”里面的对应选项，确认提交推送正常。如果能够在 Gitee 仓库页面看到更新，整套自动流程就跑通了。

4. 笔记管理技巧与插件搭配

4.1 文件夹结构与标签双链怎么组织

仓库同步只是手段，记笔记本身才是核心。Obsidian 允许用文件夹组织笔记，但它真正有魅力的地方在于双链和标签体系。我的组织方式是“剥洋葱式”的，由外到内分四层：

• 第一层是收件箱，用来存放临时想法、一闪而过的念头、尚未整理的信息流摘抄。这一层不需要分类，定期清空即可。
• 第二层是项目笔记，按正在做的事划分，比如工作项目、学习计划、读书笔记。这一层的特征是“有生命周期”，项目结束就归档。
• 第三层是常青笔记，存放哪些已经成型、可以反复引用的知识点，每条笔记尽量做到“一句话能说清核心观点”，方便以后引用。
• 第四层是资源目录，放图片、PDF 等附件，通过相对路径与笔记关联。

文件夹层级不要超过三层，否则你自己都会找不到。真正连通知识的是双链：在笔记正文里输入[[就可以唤起笔记链接，把相关概念连起来。我不会为了链接而链接，每一条双链都问自己一个问题：后续回看这条笔记时，顺着这个链接能找到什么有价值的内容？能够回答这个问题，双链才有意义。

标签则是另一套维度。文件夹管分类，标签管状态。我用#待整理、#进行中、#已完成这类状态标签，实体标签只用少数几个大的领域，比如#技术、#读书、#生活。标签心法就是克制，一般一套笔记体系 20-30 个标签封顶，不然管理成本比收益还高。

4.2 提升生产力的核心插件推荐与避坑指南

Obsidian 的插件生态是我见过个人知识管理工具里最丰富的，但插件装太多反而影响启动速度和稳定性。这里分享几个我用了超过半年、真正改变体验的插件：

• Dataview：允许你用类似 SQL 的语法查询笔记元数据，实现“自动生成某标签下所有笔记的列表”这类需求。比如我维护过一个技术标签下的阅读清单，一句查询就搞定，不用手动维护目录。
• Calendar：日历视图，点击日期快速创建日记，搭配 Daily Notes 官方核心插件使用，适合做每日记录和回顾。
• Templater：模板引擎，可以定义新笔记的初始结构，比如日记自动带上当天日期和待办区域。这是减少重复劳动的关键插件，新手可以直接用官方模板功能过度。
• Excalidraw：在笔记内手绘思维导图、示意图，适合视觉型整理。
• WordBuddy：这个插件的主要价值是和 Word 文档对接，可以导入导出 Word 格式，对于需要和同事/导师交换文档的场景很有用。
• 飞书连接相关的插件，比如 Larksuite 集成，适合公司用飞书协作的团队环境，可以直接把飞书文档和 Obsidian 笔记互相链接，减少复制粘贴的碎片化。虽然我不常用，但如果公司强制用飞书，这类插件可以试试。

优秀插件很多，但避坑更重要。第一，插件和 Obsidian 版本有兼容性要求，升级 Obsidian 前先看一下已安装插件是否适配，否则会出现打不开、白屏等问题。第二，尽量从官方社区插件市场安装。从第三方网站下载的插件可能带恶意代码，而笔记里往往存着大量个人隐私，这个风险必须重视。第三，插件一旦不用就卸载，每多一个插件都是未来排障成本的一环。

顺带提一句，网上有人折腾“Obsidian 和 Trae 搭建知识库”、“Hermes Agent 之类的 AI 助手接入 Obsidian”，这类玩法本质上就是通过插件或外部脚本，把 AI 能力注入到笔记系统里。AI 可以做摘要、分类、联想推荐，但目前还很难替代“人自己梳理知识”的过程。我的建议是花哨玩法等到基础同步和笔记规范都稳定之后再碰，不然很容易陷入“装备党”陷阱：工具越搞越复杂，笔记却越来越没积累。

4.3 关于 Gitee Pages 发布笔记的一些实在看法

热词里经常出现 Gitee Pages，我也被问过很多次：“能不能把我的 Obsidian 笔记发布成博客，托管在 Gitee 上？”这里要泼一点冷水：Gitee Pages 的启用需要实名认证，并且官方规则变动频繁，功能可能随时调整，稳定性并不高；很多网上教程里的免费 Pages 用法已经不能照搬。如果你真的想把笔记公开分享，更稳妥的方案是部署到其他静态托管平台，或者用自己购买的轻量服务器。笔记发布是内容展示的事，和笔记同步走两条路，我一直建议不要把两者混在一个仓库里。同步仓库保持私有，发布仓库单独建和维护，这样两条线互不干扰，出问题也好定位。

5. 常见问题与排查技巧实录

5.1 Obsidian 打不开或启动异常的排查思路

不少朋友卡在第一步：Obsidian 下载好之后双击没反应，或者一直转圈打不开。我总结的排查顺序是：先看安装路径是否正常，路径里有中文容易触发一些插件或索引问题；再看系统防火墙和安全策略是否拦截；然后检查库文件夹权限，如果是从压缩包解压出来的库，Windows 经常因为“隐藏文件选项”没开而导致 .obsidian 目录被忽略，Obsidian 认为这不是一个有效的库。

更常见的是插件问题：前一天还好好的，第二天突然打不开，多半是某次自动更新把插件和主程序搞出了兼容性问题。这种情况可以尝试“安全模式”启动，Obsidian 启动界面上按住 Shift 键，可以让插件暂时全部禁用，进入后就能正常打开，再逐个排查哪个插件是凶手。禁用插件只需要在第三方插件列表里关掉对应开关，不用删除文件，非常方便。

5.2 附件在 Typora 中读不出来是怎么回事

Typora 和 Obsidian 我都重度用过，两者都基于 Markdown 标准，但对附件路径的处理方式不同，这直接造成了一个高频率的问题：“Obsidian 里的图片在 Typora 里显示不出来，提示文件路径错误。”

原因在于 Obsidian 默认的链接格式是 Wiki 风格，比如![[图片.png]]，而 Typora 只识别标准 Markdown 图片语法![](图片.png)。解决思路有两个：第一，在 Obsidian 设置-文件与链接里，把“新链接格式”改为“基于当前文件路径”，这样新插入的链接就转成标准 Markdown 的相对路径；第二，对已有的![[ ]]链接，可以用一个叫 Obsidian Markdown Converter 的插件做批量转换。另外一个容易忽略的点是附件存放位置：如果 Obsidian 设置里把附件的默认位置设为“库根目录”而不是“当前文件所在文件夹”，那 Typora 按相对路径去找图片就会失败。我的建议是所有的附件跟随当前笔记放，文件夹会看起来乱一点，但笔记的可移植性最好。把笔记文件连同附件一起拷贝给同事时，相对路径不发生断裂，这比整齐的目录结构重要得多。

5.3 Git 同步冲突与误操作的现场复盘

Git 同步偶尔会出现“冲突”或者“无法自动合并”的报错。冲突的本质是两台设备同时对同一个文件的同一行做了不同修改。如果你习惯晚上在家改笔记，白天在公司也改了同一篇，就很容易触发。

遇到冲突不要慌，Obsidian Git 插件会在冲突文件旁生成一个.conflict版本，你可以在编辑器里同时看到两份内容，手动决定保留谁的修改。如果你想尽可能避免冲突，记住一条使用纪律：切换设备前先手动点一下“拉取”，确认拿到最新版再开始编辑。另一个实用技巧是把自动拉取间隔调小一些（比如 5-10 分钟），这样即使忘了手动操作，插件也会在后台尽量保持仓库最新。

误操作方面，我最常遇到的场景是“把笔记删了或者改坏了，想退回之前的版本”。Git 的好处在这里充分体现：在 Gitee 仓库页面可以看到每个文件的提交历史，找到上一个可用版本，直接查看或恢复。本地命令行恢复某个文件到上一个提交：

git checkout HEAD~1 -- 你的笔记文件名.md

这条命令会从上一个提交中取出该文件并覆盖本地版本。注意这只是恢复文件内容，不会影响其他文件。如果是整个库回退，就不要随便用git reset --hard，那会把所有未推送的本地提交直接丢弃，大概率会误伤。真要回退，优先在 Gitee 页面上操作，远程仓库回滚到某个历史提交后，再在本地拉取即可。

5.4 权限、密钥和其他 Gitee 使用细节

• 推送时报“Permission denied（publickey）”：通常是 SSH 公钥没有配置对，或者本地 git 没有找到私钥。先执行ssh -T git@gitee.com测试，如果提示成功，再看 Obsidian Git 插件里的“私钥路径”是否填写正确。Windows 上建议写完整路径，比如C:\Users\你的用户名\.ssh\id_ed25519，有些插件版本对~展开支持不友好。
• 推送到远程时被拒绝“remote: error: GH007：Your push would publish a private email address”：这是 Gitee 对匿名邮箱的保护机制，可以在 Gitee 设置里开启“屏蔽命令行推送中暴露的邮箱地址”，或者把本地 git 的 user.email 换成 Gitee 绑定的隐私邮箱。
• 仓库大小超限：Gitee 单个仓库容量和单个文件大小都有限制。笔记仓库一般不会触发，但如果插入大量图片、PDF，仓库会很快膨胀。我的经验是附件尽量压缩，超过 10MB 的文件不要放入笔记库，改为网盘链接引用。
• 其他设备克隆仓库：新电脑上安装 Git、配置 SSH 密钥后，执行：

git clone git@gitee.com:你的用户名/notes.git

然后把文件夹作为本地库导入 Obsidian，再装好 Obsidian Git 插件，整套环境复制完成。这也验证了“配置目录 .obsidian 随着仓库一起走”的好处。

5.5 手机端同步的补充实践

很多人最终会问手机端怎么同步。Obsidian 手机端没法直接运行 git 命令，但有几个替代方案：一是利用手机上第三方 Git 客户端（比如 MGit 或 Working Copy，后者 iOS 体验较好）来拉取、提交、推送仓库，然后再用 Obsidian 打开本地文件夹。这种方式操作上多一步，但好在稳定可控。二是像 Mobile Obsidian Git 一类的插件可以在 App 内执行有限 Git 操作，实测下来成功率尚可，但要求手机应用后台常驻，网络状况不好时容易卡住。三是干脆只把手机当作“快速记录”入口，写入收件箱文件夹，回到电脑前再统一用 Git 同步。我个人用的是第三种思路：手机端保持简单，复杂整理全部留给电脑。这样手机端不需要配置 SSH，也不需要处理冲突，体验最轻松。注意，用这种方式时千万不要同时在手机端和电脑端编辑同一篇笔记，否则冲突概率很高，手机端又不太好解决。

最后再分享一点个人体会

经过这么长时间的实践，我最大的体会是：一套笔记系统能不能长期坚持下去，技术只占三成，习惯占七成。工具选再花哨，如果每天都不打开笔记，一切等于零。Obsidian 加 Gitee 的组合给我带来的真正价值，不是“同步”这个动作本身，而是让我敢在笔记里放肆地写、大胆地改。因为我知道每一个版本都会被记录下来，每一次误删都有可能找回，每一台电脑上的修改最终都会汇合到一个地方。这份安全感是很多在线笔记给不了的，也是我最终放弃官方同步、坚持自建这套方案的核心原因。如果你也被笔记同步的问题困扰过，不妨按这篇流程搭一次，半小时的投入换来的是长期的省心。往后笔记越写越多，这套底层基础设施会越来越显得值得。