★ FEATURED ARTICLE 1. 为什么笔记都要放本地了还要再折腾一套云同步先说结论Obsidian这种本地优先的笔记软件天生和网盘同步合不来反而是Git类工具和它匹配度极高。Obsidian的所有笔记都是普通Markdown文件存在你电脑的某个文件夹里。这种设计的最大好处是——没有厂商锁定没有数据库绑架哪怕十年后这个软件不更新了你的笔记依然是可以直接用文本编辑器打开的一堆md文件。看似简单但恰恰是这个文件即笔记的架构决定了它的同步方案和Notion、语雀这类云端笔记完全不同云端笔记自带同步而Obsidian需要你自行解决多设备文件一致的问题。早期我试过把整个Obsidian库丢进OneDrive、坚果云这类网盘里最开始确实能用但用久了就发现问题。网盘的同步是文件快照级的它默认你在一台设备上有唯一权威版本。一旦你在手机和电脑上同时改了同一个md文件网盘会悄悄生成一个冲突副本文件名变成something(1).md然后两个版本就在一个库里并存你根本不知道哪个是最新的。更麻烦的是Obsidian在手机上编辑时文本是实时写入的如果这时网盘正在后台同步很容易出现文件被旧版本覆盖。我损失过两次笔记之后彻底放弃了网盘方案。这行的朋友应该都听说过Git但多数人只把它当代码工具。其实Git解决的核心问题——版本管理、冲突处理、历史回溯——恰恰是笔记场景最需要的。每一个笔记文件就是一行行文本Git能逐字对比两个版本间的差异能在你做错了之后回滚到任何一次历史提交。把Obsidian库做成Git仓库后等于给你的笔记加了一个时光机。那为什么选Gitee而不是其他平台核心就一句话国内访问稳定创建私有仓库免费功能不缩水。我经历过用境外代码托管平台时频繁断连、push到一半超时的痛苦换到Gitee之后这些问题基本绝迹。加上Gitee本身支持私有仓库、SSH公钥认证、Pages静态托管、Webhook这些功能拿来当笔记同步中枢绰绰有余。这套方案的目标很明确解决Obsidian在Windows、macOS、Android、iOS等多端之间的双向同步同时享受版本历史、集中备份、网页预览等额外收益。全部使用官方免费功能不需要NAS不需要按月订阅只要有一个Gitee账号就能跑起来。对动手能力有基本要求但跟着下面的流程走一圈你会发现每一步都是合理的。2. 从装软件到建仓库把笔记库和Gitee串起来的完整步骤2.1 安装Obsidian并规划库文件结构Obsidian从官网下载安装版即可移动端直接在应用商店搜Obsidian注意认准图标别装错第三方套壳。打开之后第一步不是新建笔记而是新建一个库。库里可以按领域分子文件夹比如工作、学习、日记、随手记。目录结构完全由你掌控没有强制的模板。但强烈建议在一开始就想清楚分类体系后期文件多了再重构目录所有反链和链接都要重对一遍非常痛苦。我这套库的结构长这样你可以参考知识库/ ├── 00-收集箱/ # 快速记录还没归类的内容 ├── 10-项目/ # 按项目名建子文件夹 ├── 20-领域/ # 按知识领域比如编程、写作、投资 ├── 30-日记/ # 日记或日志按年份月份分 ├── 90-附件/ # 图片、PDF等非md文件 ├── .obsidian/ # Obsidian配置文件目录自动生成 └── .trash/ # 回收站.obsidian这个目录需要重点说一下。它保存了你的插件列表、快捷键设置、主题、面板布局等全部配置是Obsidian的灵魂。很多教程让你把它写进.gitignore里忽略掉这样多端同步后每台设备的插件状态各自独立但其实这会让配置同步的价值完全丢失。我的建议是.obsidian整个目录同步只忽略其中workspace.json这个文件因为workspace记录的是你上次打开库时的窗口布局比如打开了哪些面板、光标位置这种东西每次关闭Obsidian都会变同步它只会制造无意义的冲突。而插件、主题、快捷键配置完全值得跨设备统一。在Gitee的仓库里.obsidian目录建议也提交。注意移动端上Obsidian默认不加载社区插件需要在设置里开启允许第三方插件安装我后面会单独讲。2.2 在Gitee上创建仓库许可证和可见性怎么选这一步很多人会卡在开源许可证选什么上——其实只要你的库设成私有Private许可证选无就好。许可证是给开源项目用的法律声明文本私有仓库根本不对外公开没必要选。仓库名称随意比如notes-backup。路径建议全小写加连字符比中文路径在终端里敲命令省事。可见性选私有。创建完成后不用勾选初始化仓库因为我们本地已经有一个完整的笔记库目录了直接把它推上去就行。2.3 本地库变成Git仓库并完成首次推送假设你的Obsidian库在D:\knowledge-base下打开终端进入该目录执行cd D:\knowledge-base git init git add . git commit -m init: 笔记库初始提交接着把远端地址绑定上。这里更推荐SSH地址而不是HTTPS原因我在第3部分单独说git remote add origin gitgitee.com:你的用户名/notes-backup.git git push -u origin master如果你此刻还没来得及配置SSH密钥Git会报错提示权限问题。所以先别急着执行这步先去把第3部分的SSH密钥配好再回到这里push。一般来说首次push前先把.obsidian/workspace.json加入.gitignore再推可以减少后续冲突次数。echo .obsidian/workspace.json .gitignore git rm --cached .obsidian/workspace.json git commit -m ignore workspace layout git push执行完这些你的整个Obsidian库就安全地躺在Gitee私有仓库里了。现在你可以在另一台设备或手机上用同样方式clone但更推荐的方式是安装Obsidian Git插件让同步自动化具体在第4部分。3. SSH密钥配置一次完成告别每次输密码3.1 为什么必须配SSH而不是一直用HTTPS很多第一次接触Git同步的笔记用户会问我用HTTPS地址不也能push吗为什么要配SSH密钥HTTPS确实能用但它有两个硬伤。第一每次push和pull都要输账号密码如果Gitee开了双重验证你还得生成一个私人令牌把它当密码用麻烦且容易忘。第二HTTPS的认证方式在自动化脚本和插件自动提交时很痛苦Obsidian Git插件设置在后台自动提交时如果遇到HTTPS认证弹窗整个自动流程就直接卡死了。而SSH认证是基于公钥的非对称加密私钥留在你本机公钥放到Gitee账号里之后的每次Git操作都会自动完成认证不需要输任何密码。只要配一次换来的是无限次免密操作。这笔账非常划算。3.2 生成密钥并把公钥放进GiteeWindows用户打开PowerShellmacOS和Linux打开终端执行ssh-keygen -t ed25519 -C 你的邮箱example.com参数里的-t ed25519是指定加密算法Gitee支持rsa和ed25519两种ed25519更短、更快、安全性也足够。如果因为某些历史原因必须用rsa可以写成ssh-keygen -t rsa -b 4096 -C 你的邮箱example.com生成过程中会问两个问题保存路径默认~/.ssh/id_ed25519和私钥口令passphrase。保存路径直接回车用默认值。私钥口令这里我给的建议是如果你只是个人使用桌面电脑也不容易被别人碰到可以不设口令直接回车跳过如果你的电脑有多个用户或者经常在外面用还是设一个口令更稳妥。设了口味后每次git操作可能会要求你输入这个口令但Windows的OpenSSH客户端会把解锁后的私钥加载到系统服务里后续一段时间内再操作就不需要重复输入了。密钥生成后屏幕上会出现一串指纹和随机数图randomart image。公钥内容在这个文件里cat ~/.ssh/id_ed25519.pub复制输出的完整字符串以ssh-ed25519开头到邮箱结尾然后登录Gitee网页端进入 设置 - 安全设置 - SSH公钥把内容粘贴进去标题随意填一个能区分用途的名字比如我的笔记本-2025。提交后公钥就生效了。验证是否配置成功在终端执行ssh -T gitgitee.com第一次连接会提示是否信任该主机输入yes回车。如果看到欢迎信息并报出你的Gitee用户名就说明认证链路完全打通了。3.3 密钥配置常见失败场景我见过不少人在这一步栽跟头总结几种最常见的公钥粘贴时删了中间的换行或首尾编码不完整整个Auth会被拒绝。公钥是一整行的长字符串粘贴时不要把换行符带进去。仓库的remote地址用的是HTTPS而你已经配好了SSH密钥这时依然要输密码。需要修改仓库地址git remote set-url origin gitgitee.com:你的用户名/仓库名.git多台设备各自生成了不同的密钥需要在Gitee上添加多个公钥。Gitee允许一个账号挂多把公钥直接重复第3.2节的操作即可别把新设备上的公钥覆盖老设备。公司电脑有安全软件拦截了SSH端口22一种绕不开的替代是换用HTTPS协议加令牌但这会失去免密优势。另一种是把端口改成443Gitee支持SSH over HTTPS端口在~/.ssh/config里加Host gitee.com HostName gitee.com User git Port 443这类企业网络环境问题并不常见你可能用不上但万一遇到能少走一周的弯路。4. Obsidian Git插件让同步像呼吸一样自然4.1 插件安装与基础配置光靠手动命令行同步用不了三天你就不想同步了。笔记是个高频动笔的程序一天少说几十次新增和修改如果每次编辑完去终端敲一遍git add / commit / push坚持不了太久。Obsidian的Git插件obsidian-git就是来解决这个痛点的。它把提交和推送变成后台动作你可以设置每隔几分钟自动执行一次全程无感。安装方式Obsidian设置 - 第三方插件 - 关闭安全模式 - 浏览 - 搜索Git - 找到Obsidian Git插件并安装。安装后会多出一片设置项主要的集中在Automatic Backup自动备份区块。我把我现在用的配置列出来你直接抄即可配置项我的值说明Auto backup interval (minutes)10每隔10分钟自动commitpushAuto pull on startup开启启动库时先拉取远端最新内容Pull on commit开启触发自动提交前先拉一次远端Push on commit开启提交完成后立即推送到远端Commit messagevault backup: {{date}}提交信息用时间戳区分Backup behaviorCommitPush不要选Commit only否则永远只在本地Author name你的昵称移动端可能默认是注释掉的状态这里插一句10分钟的时间间隔是一个平衡值。太短了手机端频繁唤醒网络耗电太长了一旦设备丢失丢失的最近修改就多。如果你是重度手机录入党建议把间隔压缩到5分钟如果只在电脑前工作15分钟也够。还有一个容易踩的坑Obsidian Git插件在移动端生效的前提是你本机已经能通过SSH认证访问Gitee。手机上生成密钥比较麻烦我目前比较推荐的做法是在电脑上生成密钥后把私钥文件通过安全的渠道传到手机放到Termius或MGit能访问的位置。如果觉得繁琐移动端可以用Gitee配套的码云git类App配合手动切换不求自动化只求能拉取查看。我自己最终还是在手机端装好了完整流程过程虽然折腾但完成后确实再不用管同步了。4.2 自动提交、拉取与冲突缓解机制自动间隔设置后插件在后台做的事和手动输入命令完全一致先执行git add -A再执行git commit然后git push。如果你开启了Pull on commit每次提交前它会先执行git pull这样就把远端的最新修改拉到本地降低覆盖别人修改的概率。很多人担心自动提交会把正在编辑中的残留内容也提交上去——比如写了一半的句子。我的看法是笔记不是代码交付不存在半成品不能提交的洁癖。反而正是这种垃圾中间态让你能在三天后追查我当时在这个地方改了什么。版本历史里保留中间状态比只有最终完美状态要有价值得多。但要注意自动提交频率越高产生的垃圾commit就越多日志会显得很杂。如果不喜欢噪音可以把commit message改成类似auto-sync {{date}}这样的固定格式然后定期在某个时间点做一个整理性commit手工提交一次写清楚今天完成了什么。4.3 断网与离线编辑时的行为Obsidian离线状态完全不影响编辑因为文件在本地。恢复联网后Git插件会在你手动触发或下一个自动周期到达时按队列把积攒的commit推上去。如果你离线期间在另一台设备上也在编辑同一个文件恢复同步时就会触发冲突会看到文件里出现 HEAD 我在A设备上的修改 你在B设备上的修改 b94104c这并不可怕。在Obsidian里打开这个文件把不需要的部分删掉保留你要的保存后执行一次sync命令面板 - Git: Commit and Push就把冲突解决了。Git插件也带有merge tool选项不过我建议大多数场景手动合并就够工具反而容易误操作。唯一要注意的是其他笔记软件比如Notion、语雀在多端同时编辑同一内容时是最后一次写入覆盖你没有机会对比而Git从机制上逼迫你自己选择保留哪个版本。这个过程表面上费了点事实则在保护你的数据完整性。5. .gitignore该怎么配才能既同步配置又不产生冲突5.1 配置文件的取舍逻辑.obsidian目录里不同文件承受冲突的容忍度完全不同。下面这张表是根据我在多场景下的经验整理的文件/目录是否同步理由.obsidian/plugins/同步插件本体跨设备统一管理不装插件我会很难受.obsidian/themes/同步主题外观统一避免一台设备换主题另一台变回默认.obsidian/hotkeys.json同步快捷键习惯统一可以在配置后复制一份做备份.obsidian/snippets/同步CSS片段属于自定义样式必须同步.obsidian/workspace.json忽略每次打开自动改纯噪音文件同步反而易冲突.obsidian/daily-notes/自动如启用日记模板模板文件应同步.trash/按需我建议同步前先清空垃圾桶没必要传上去在这个场景里我最终放弃在.gitignore里写上.obsidian里的核心配置而是只忽略workspace.json。这个决定源于一次真实经历有一次我在三台设备上分别加了不同的插件因为workspace被忽略了所以各设备插件配置互不干扰但我希望统一的快捷键习惯无法达成。后来我恢复了同步.hotkeys.json每次换设备时Obsidian会问是否应用新配置同意即可。5.2 多端仓库的克隆流程新增一台设备的流程非常简单安装Obsidian登录Gitee网页端找到仓库复制SSH克隆地址在Obsidian里打开其他库 - 通过URL克隆仓库这里Obsidian Git插件会直接接管git clone过程填写本机路径选好本地库目录确认后它会把整个仓库克隆下来首次打开库会让你选择信任作者同意后插件就绪。注意这种方式不需要你先git clone再打开Obsidian全程在Obsidian内完成对不会命令行的朋友非常友好。但前提是这台设备上已经完成了Git客户端安装以及SSH密钥已经加入Gitee步骤同前。手机端苹果设备可以通过-ish等App配置SSH安卓上我试过MGit和Obsidian Git插件组合就绪后效果和PC端一致。多设备同日使用时最容易发生的问题反而是我自己和自己冲突A设备自动提交了c.mdB设备也在编辑c.md但还没提交B触发拉取后就和本地修改产生了冲突。缓解方法是把自动间隔调到足够短让A设备的推送尽量在B设备编辑之前就到位。现实中很难做到完美但插件设置Pull on commit后冲突概率已经降到我可以接受的范围至少比网盘那个随机的冲突副本靠谱太多。6. 把笔记库变成个人网页Gitee Pages的发布思路进阶玩法6.1 Gitee Pages能做什么Git同步解决的是笔记在多设备间一致的问题而Gitee Pages解决的是把笔记展示给人看的问题。你也可以把笔记当成静态网站发布出去。Gitee Pages是Gitee官方提供的静态网页托管服务只要你的仓库里有一份HTML文件它就能通过固定网址对外访问。而Obsidian里的Markdown文件可以通过工具转换成静态HTML。具体怎么转换主流方案有两个用Obsidian的第三方插件比如Enhancing Export或obsidian-export把整个笔记库导出为干净的结构化HTML或者用静态站点生成器比如Hugo搭配Markdown目录作为内容源生成一套带导航的网站。前者的优势是零成本所见即所得后者的优势是自带站点框架像真正的博客。我个人的选择是Hugo它天然支持Markdown文件可以把Obsidian的文件路径直接映射成站点文章主题丰富也支持标签和目录导航。6.2 可行的部署路径与限制Gitee Pages和某些境外托管平台不同它的审核和部署需要手动操作。每次内容更新都要重新部署一次不是自动监听仓库变化。使用流程在本地把笔记库构建为静态站点HTML文件把生成静态文件推送到同一个仓库建议使用单独的部署分支比如deploy分支登录Gitee仓库页面选择服务 - Gitee Pages填入部署分支和目录点击启动生成一个免费网址把链接发给能访问的人。这条路径适合做个人知识库分享或者项目文档展示。但有两个前提条件必须留意如果你的仓库是私有的Pages不会对外展示如果内容涉及敏感信息比如日志里写了具体业务细节发布到公开全网就是一个数据泄露风险。所以我的经验是只把刻意整理过的公共知识放进公开Pages分支其余一律留在私有库里两者完全分离。顺带提一个省钱高级玩法你本地做好HTML之后也可以抛开Pages直接部署在其他静态托管服务上同样拿Obsidian导出的文件做底料。这个选择全看你对平台喜好做法一样。7. 出了问题怎么排查从Obsidian打不开到git操作失败的追踪链路7.1 Obsidian自身故障的常见诱因热词里有obsidian打不开这确实是会发生的而且很多场景和同步配置有关。最常见的原因插件冲突。我遇到过装了某个未更新主题后Obsidian每次启动就白屏或卡在加载界面。排查思路很简单先打开设置或直接修改配置文件在.obsidian/plugins目录下把可疑插件目录改名比如加上.bak后缀重启Obsidian看是否恢复。如果恢复了就是那个插件的问题逐级排除。第二个常见原因库文件过大或文件数过多。如果你把十几G的附件塞进同一个库Obsidian会在每次启动时遍历整个文件夹等待时间越来越长。解决方案是把库拆成多个比如主知识库和素材库Obsidian支持工作区同时打开多个库互不影响。第三个场景workspace.json损坏。这个文件里记录着窗口状态如果它在某次非正常退出时被写坏可能导致打不开。把该文件临时改名删除Obsidian就能回到默认布局。反正它已经被我们加进.gitignore了删了不心疼也不算破坏配置。7.2 Git操作失败的分步排查如果你打开Obsidian后提示Git sync failed先别慌这是插件把错误信息显示出来了按以下顺序排查查看错误详情先到Obsidian命令面板执行Obsidian Git: Show current backend error插件会直接弹出git的原生报错。如果是Authentication failed说明SSH密钥没配对或路径不对回到第3.2节重新验证一遍ssh -T gitgitee.com。如果是Connection timed out检查网络是否正常或者是公司内网屏蔽了外网连接。可试试push小文件测试。如果push时提示rejected说明远端有本地没有提交的更新去命令面板执行一次Pull with rebase再commit push这条最容易在手机上发生因为手机端同步不及时。Gitee还有一个很隐蔽的限制单次push的包体不能过大。如果你的附件里有超过100MB的文件push会被拒。所以附件尽量走压缩或图床md文件本身轻量没这个问题。7.3 数据救回的兜底方案Git的强项之一就是历史回溯。当你发现某篇笔记被误删或改坏了在终端进入库目录执行git log --oneline -- 文件夹/笔记.md找到这条笔记最近一次正常提交的commit hash然后git checkout commit-hash -- 文件夹/笔记.md这条命令会把该文件恢复到指定提交时的内容然后commit一下笔记就回来了。同理如果整个库出了大问题也能用git log全局找到所有历史状态。我在实际整理笔记库的时候定期会在电脑上把整个库压缩打包一次存到另一个硬盘或外部存储里。这纯粹是强迫症式防呆但配合Gitee的日常增量备份等于给笔记上了三重保险本地一份、云端一份、冷备一份。哪怕Gitee的服务出问题我也能从冷备里恢复全部内容。最后提一下整个方案的核心其实就是一句话Markdown文件是核心资产Obsidian和Gitee只是管理、同步这份资产的工具。把这句话悟透你就不会受困于某一个单一软件的功能边界了。像我后来用Obsidian时还会配合飞书、Trae这类工具做知识库联动——但底层的数据始终是那堆md文件Gitee永远是它们最安稳的家。
阅读完成 · 觉得有帮助？
