自从开始重度使用 Obsidian 做笔记我踩过不少同步的坑。用过网盘延迟和冲突文件让人抓狂试过付费同步服务对本地文件的管理总觉得不够顺手。后来把目光转向 Gitee用 Git 仓库当存储后端一套组合拳下来本地写作的流畅感保住了云端备份也稳稳落地。这篇就把我自己的完整实践记录拆开讲清楚从为什么选 Gitee 到一步步配置、避坑全盘托出。1. 为什么 Obsidian 笔记要配 Gitee 云存储Obsidian 这个笔记工具核心卖点就是本地优先。所有笔记都是纯 Markdown 文件存在你自己电脑的文件夹里不依赖任何云服务加载速度快数据完全属于你。可问题也随之而来——没云同步的话换台电脑、重装系统或者手机临时想看一眼笔记都会变得非常被动。云存储方案常见的有几种商业网盘、笔记自带的官方同步服务、Git 仓库托管平台。我逐个试过之后选择了 Gitee 作为主力云存储原因很实际速度快且稳定国内访问 Gitee 的仓库克隆和推送速度明显优于海外平台日常同步几乎感觉不到等待。免费额度够用纯文本笔记占不了多少空间Gitee 免费版个人仓库完全能满足。版本历史天然存在Git 本身就有提交历史等于每改动一次笔记就存了一份快照误删、写崩了都能找回。和 Obsidian 的本地化逻辑一致Gitee 仓库只是存储后端笔记依然在你本地文件夹里。就算云端出问题本地文件一概不受影响。适合的人群也很清晰Obsidian 的深度用户、多设备需要同步笔记的上班族、重视笔记数据自主权的技术型内容创作者。它解决的痛点是免费、可控、不锁数据的跨设备笔记同步问题。说明一下Gitee 也可以开启 Pages 服务把笔记发布成静态网站但那是另一套玩法。这篇聚焦的是用 Gitee 仓库做笔记的云存储和版本管理这个核心需求。2. 核心方案拆解Obsidian Git 的工作机制2.1 同步流程的完整链路这套方案本质上是拿 Git 当 Obsidian 的云盘来用。整个同步逻辑分三层本地笔记库Obsidian 的 Vault 文件夹里面全是.md文件和附件。这是你真正写作、编辑、思考的地方。Git 仓库在本地笔记库中初始化一个 Git 仓库通过git add、git commit、git push把本地变更推送到远程。Gitee 远程仓库托管在 Gitee 服务器上的裸仓库充当所有设备的中央节点。每次同步的动作就是本地提交记录改动→ 推送到 Gitee上传备份另一台设备上就是拉取 Gitee 仓库下载最新→ 打开 Obsidian 继续编辑。用生活化的比喻本地笔记库是你在工位上正在写的稿件Git 提交是存档动作Gitee 仓库是公司文件柜。存完档把文件放进文件柜换一个工位再从文件柜取出来继续写。2.2 为什么用 Git 而不是网盘直接同步对比一下常见方案就会很清楚方案优势不足系统网盘如某度盘、某果 iCloud简单、自动同步延迟高冲突文件多笔记格式偶尔被干扰隐私性一般Obsidian 官方同步体验好端到端加密需要订阅付费价格不算便宜Git Gitee免费、全量版本历史、可控性强需要了解 Git 基础命令首次配置稍麻烦选 Git 方案的人通常更在意数据是自己的、历史版本能找回这两点。Gitee 仓库和本地文件是标准的 Git 镜像关系所有笔记的历史版本都存在提交记录里配合 Git 客户端可以回滚到任意时间点的状态。2.3 核心决策要点清单我在搭建这套同步方案时定了几个关键约束供你参考仓库尽量设为私有。笔记属于个人知识资产公开仓库相当于把自己的笔记展览出去一般不推荐。不用 Obsidian 自带的“同步”设置项。Obsidian 官方不内置 Git 同步需要靠插件或外部工具完成。市场上主流方案是 Obsidian Git 插件后面会细说。仓库文件名和路径避免特殊字符。Windows、macOS 和 Git 对文件名的兼容性有差异命名规范一点能省很多事。附件也纳入 Git 管理。笔记里的图片、PDF、音频等附件如果不同步换设备后链接会直接断裂。所以附件文件夹默认是 Vault 根目录也要一起纳入提交。3. 实操篇从零搭建 Obsidian 笔记库与 Gitee 仓库3.1 本机准备工作安装 Obsidian 和 Git 环境第一步自然是装好工具。Obsidian 的安装没有太多复杂操作直接从官网下载对应系统版本一路下一步就可以。安装好后新建一个 Vault仓库库Vault 本质上就是一个普通文件夹Obsidian 会在这个文件夹里建一个.obsidian的配置目录存放你的设置和插件。Git 环境的安装稍微要注意一点。Windows 上我推荐去 Git 官网下载 Git for Windows安装时有一个很关键的选项——调整 PATH 环境变量务必选择 Git from the command line and also from 3rd-party software 这个选项否则后续在 Obsidian 插件里调用 Git 命令时会找不到命令。macOS 用户可以用 Homebrew 执行brew install git安装。装好后在命令行终端里跑一下git --version能输出版本号就说明 Git 环境OK了。3.2 Gitee 仓库创建与 SSH 密钥配置接下来是 Gitee 端的准备。先登录 Gitee 网站点击右上角新建仓库。填写仓库名称比如obsidian-vault。这里要特别留意两个配置仓库是否私有选私有才能保证笔记不公开。初始化仓库设置我强烈建议创建仓库时不要勾选使用 Readme 文件初始化这个仓库也不要添加 .gitignore 和开源许可证让仓库保持完全空的状态。理由后面一步会说到因为如果远程仓库有初始提交本地首次推送时就需要处理合并冲突徒增麻烦。创建完成后需要配置 SSH 密钥这样本地推送代码时不需要每次输密码。SSH 密钥的配置分为三步第一步在本地生成 SSH 密钥对。Windows 打开 Git Bash注意不是 PowerShellmacOS/Linux 打开终端执行ssh-keygen -t ed25519 -C 你的邮箱一路回车即可。生成的密钥默认在~/.ssh/id_ed25519私钥和~/.ssh/id_ed25519.pub公钥。第二步把公钥添加到 Gitee。在终端执行cat ~/.ssh/id_ed25519.pub输出内容全部复制。然后打开 Gitee 网站依次进入设置 → 安全设置 →SSH 公钥把复制的内容粘贴进去标题随便填比如我的笔记本。保存即可。第三步验证密钥是否生效。终端执行ssh -T gitgitee.com首次连接会提示是否信任主机输入yes。看到类似Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.的提示就说明 SSH 配置成功了。3.3 本地仓库初始化与首次推送SSH 配好后开始在本地把笔记库变成 Git 仓库。打开终端进入 Obsidian 的 Vault 根目录cd /你的路径/你的仓库库名初始化 Git 仓库git init设置 Git 用户信息第一次使用的话git config --local user.name 你的名字 git config --local user.email 你的邮箱这里用--local是只对当前仓库生效不影响 Git 全局配置方便不同仓库用不同身份。然后把所有文件加入暂存区并做首次提交git add . git commit -m init: 初始化笔记仓库接下来把本地仓库和 Gitee 远程仓库关联起来。在 Gitee 仓库页面有仓库地址选择 SSH 格式的地址形如gitgitee.com:你的用户名/obsidian-vault.git。执行git remote add origin gitgitee.com:你的用户名/obsidian-vault.git git push -u origin master注意有些系统默认分支名是master有些则叫main。Gitee 新建空白仓库通常默认分支是master。推送前用git branch看看当前分支名保持一致就好。如果想统一成main可以执行git branch -M main修改分支名后再推送。推送成功后去 Gitee 仓库页面刷新就能看到你笔记库里的所有文件都躺在云端了。到这里手工同步方案已经跑通。但每写几行字就手动敲一遍 Git 命令显然不现实。所以下一步要引入自动化同步。3.4 用 Obsidian Git 插件实现自动化同步Obsidian 社区有一个叫 Obsidian Git 的插件能直接在 Obsidian 内部完成 Git 的 add、commit、push、pull 操作还支持定时自动同步。这是整个方案里最舒服的一环。安装方法很简单打开 Obsidian → 设置 → 第三方插件 → 关闭安全模式实际上新版本是直接开启社区插件功能→ 浏览社区插件 → 搜索 Obsidian Git → 安装并启用。插件装好后做几项关键配置自动定时备份插件的设置项里有一个Vault 自动备份间隔分钟我设成 10 分钟。这样每 10 分钟它会自动把当前的所有改动提交并推送一次。自动拉取在Pull 更改相关设置里可以设置拉取更新的间隔比如同样 10 分钟。这样多设备协作时每 10 分钟自动拉取云端最新内容。提交信息模板建议把提交信息设为可读的格式比如{{date}}自动带上时间戳方便回溯。配置完成后Obsidian 的左侧边栏会出现一个 Git 面板可以手动点击备份和拉取。底部状态栏也会出现一个时间图标显示上次同步时间。从此写笔记不用管同步它自己在后台默默干活。表格整理一下插件核心配置项配置项推荐值说明自动备份间隔10 分钟太频繁会把 Git 历史刷得很碎太久了风险大自动拉取间隔10 分钟多设备使用时保持内容最新提交信息模板chore: auto backup {{date}}加上日期方便查看历史推拉取超时默认即可网络好时基本不涉及3.5 多设备同步的接入方法另一台设备比如公司电脑要接入这套体系方法很简单先安装 Obsidian 和 Git并配置好 SSH 密钥在 Gitee 中把新设备的公钥也添加进去。然后在终端执行git clone gitgitee.com:你的用户名/obsidian-vault.git这会把这个仓库完整拉取到本地。接下来在 Obsidian 中打开文件夹作为仓库库选择刚才克隆下来的目录。完成。之后这台设备上 Obsidian Git 插件会负责自动拉取和推送两台设备通过 Gitee 仓库中转各写各的然后自动合并同步。4. 细节打磨让这套方案真正好用的关键技巧4.1 附件统一管理避免链接失效Obsidian 的 Markdown 链接如果附件四处乱放换设备后非常容易出现链接断裂——就是那种笔记还在、图片显示不出来的情况。我的做法是在 Vault 根目录建一个统一的attachments文件夹然后在 Obsidian 设置里把默认附件位置改成attachments文件夹。这样做的好处是Git 仓库结构清晰附件全在一个目录里同步时不会漏粘贴图片时自动归位新设备克隆下来后链接路径保持一致不会因为文件夹差异而失效。4.2 用 .gitignore 排除不需要同步的文件有些文件完全没必要进入 Git 仓库比如 Obsidian 的缓存文件、临时文件。在 Vault 根目录建一个.gitignore文件内容大致如下.obsidian/workspace .obsidian/cache .trash/ .DS_Store.obsidian目录里主要保存插件和设置其中有些缓存类文件不需要同步但插件本身还是要进仓库的否则新设备还要重新装插件。所以我只排除了其中的 workspace工作区状态和 cache其他保留。.trash是 Obsidian 的回收站目录垃圾文件不上传。.DS_Store是 macOS 的系统文件Windows 上不需要。设置好 .gitignore 后执行git add .时这些文件会被自动忽略减少仓库噪音。4.3 提交信息的规范与仓库整洁度我在实践里总结了一套自己的提交规范不一定适合所有人但很值得参考手动和自动提交统一用chore: 描述的前缀看起来整洁统一。如果某次改动比较重要比如重构了某个大笔记的结构可以临时把自动备份关掉手动提交一条信息详细的 commit比如feat: 重构AI学习笔记目录结构。避免把大文件超过 50MB放入仓库Gitee 单文件本身有大小限制而且会对仓库体积造成压力。如果有超大附件建议另寻图床或对象存储方案而不是硬塞进 Git 仓库。4.4 私有仓库的分支策略与安全习惯我个人的习惯是在master/main分支上直接写毕竟个人知识库不太需要复杂的 Git 分支管理。但安全习惯要到位Gitee 的私有仓库不等于绝对安全涉及极度敏感的内容比如密码、身份证号、银行账号我还是会拆出去不放进这个笔记库里。另外强烈建议在 Gitee 中开启仓库操作记录提醒在仓库管理设置里可以配置。这样如果有人异常访问了仓库会第一时间收到通知。虽然个人笔记被盯上的概率极低但这属于顺手就做好的安全措施。5. 常见问题与排查技巧实录5.1 推送被拒绝failed to push新设备或换仓库地址后最常遇到的就是 push 被拒绝提示类似! [rejected] master - master (fetch first)。原因通常是远程仓库有本地没有的提交。解决方法是先拉取再推送git pull --rebase origin master git push origin master--rebase会把本地提交变基到远程最新提交之上避免产生无意义的 merge commit历史会干净很多。执行过程中如果出现冲突Git 会提示具体是哪个文件冲突打开文件处理冲突标记、、后再git add和git commit即可。5.2 Obsidian Git 插件报错 检测到未提交的更改如果你开启了插件自动同步同时又手动在 Obsidian 外部修改了笔记文件比如用 Typora 编辑了同一目录的 md 文件偶尔会看到插件报这个错。原因是有文件改动还没 commit插件无法执行 pull因为未提交的改动和云端更新可能冲突。解决方式先在 Git 面板里手动执行备份把所有更改提交推送然后再点拉取。如果还是不行打开终端执行git status看看是否有冲突标记逐文件处理。5.3 SSH 连接超时或认证失败这类问题大多出在密钥配置上。常见的坑有三个公钥没有添加到 Gitee 账号下或者添加到了不同的账号里。去 Gitee 的设置页检查。本机的 config 文件如果有指定了错误的密钥文件路径。检查~/.ssh/config里的配置是否正确。某些组织的网络安全策略屏蔽了 22 端口的 SSH 连接。可以在 Gitee 仓库地址中使用 HTTPS 格式替代但那样每次推送都要输密码体验打折或者干脆确认下公司是不是允许 GitHub 类外链访问Gitee 国内通常问题不大。排查命令很好用ssh -vT gitgitee.com加-v参数会输出详细连接过程能快速定位是网络层还是认证层的问题。5.4 笔记图片不显示 / 附件丢失这个现象在新设备同步后经常出现。原因是附件文件虽然进了 Git 仓库但笔记里链接的路径是绝对路径或者指向了本机特定位置的路径换了设备后自然找不到。排查和修复方法是检查笔记里的图片语法确保是相对路径格式而不是。可以考虑安装 Obsidian 社区插件 Attachment Management 或 Consistent Attachments如适用自动把附件整理到同一目录并修正链接。在 Obsidian 设置里开启相对路径偏好设置如果有相关选项并统一附件位置。5.5 仓库体积膨胀 / 历史太大用久了仓库会越来越胖尤其是如果你习惯往笔记里塞大截图Git 每次提交都会保存一份快照历史积累下来体积可观。办法有定期整理附件不用的及时删除删除后同步一下就瘦身了。如果历史中已经混入大文件想要清理可以重写历史但不建议新手随便操作。最稳妥的方式是把笔记文件复制到一个新 Vault不带历史重新建立一个 Gitee 仓库把旧仓库归档即可。虽然丢了历史记录但对知识库本身影响不大。6. 一些独特的心得体会这套方案用了大半年最大的感受是从云端焦虑中解放出来了。以前用网盘同步笔记最怕的是冲突文件、同步延迟、某个文件被网盘锁住。现在用 Git 推送到 Gitee每一条提交都是清清楚楚的快照就算哪次改动把自己写崩了随时回退到之前任何一个节点写作的安全感一下子就上来了。拿 Gitee 当云存储还有一个容易被忽略的好处它天然就是一个备份系统。我不需要额外考虑今天有没有备份——写笔记的节奏本身就是备份的节奏10 分钟一次的自动提交等于让所有笔记始终有一个足够新的远端副本。就算笔记本当场去世换个设备克隆一下仓库笔记全回来了包括那些改坏了又觉得没用的历史草稿。还有一个很实用的操作我在手机端也配了 Obsidian手机上可以打开本地文件夹配合 Git 类客户端管理仓库偶尔通勤路上快速记一个灵感回家后 Gitee 仓库已经把手机端的内容拉回来合并到电脑端了。写作、记录、备份、跨设备四件事被一个 Gitee 仓库串在一起没有多花一分钱。最后给一个小建议如果刚开始接触这套方案别一上来就把所有插件和高级配置都堆上。先跑通最基础的手动 git push / git pull链路再装 Obsidian Git 插件做自动化最后再调附件策略和提交规范。一步步来每层都有清晰的控制点出问题也好定位。等这套跑顺了你会发现 Obsidian 真正变成了一个可以托付知识的地方。