Buck Blog | 博客正文

Obsidian 笔记多端同步实战：Git + GitHub 私有仓库（电脑 + 手机）

本指南记录如何从零搭建一套 免费、无需云存储 的 Obsidian 多端同步方案：电脑端 Ubuntu 装 Obsidian → 本地笔记目录做成 Git 仓库 → 推送到 GitHub 私有仓库 → 手机端用 Obsidian Git 插件拉取/推送，实现电脑与手机共享同一份笔记。

> 适用环境： Ubuntu/Debian（电脑端）+ Android/iOS（手机端），Obsidian 1.13.x
> 最后更新： 2026-08-17
> 核心方案： Git + GitHub 私有仓库 + Obsidian Git 插件，全程零费用

graph LR A[电脑 Obsidian] -->|git push| B[GitHub 私有仓库] C[手机 Obsidian
Obsidian Git 插件] -->|git pull / push| B

1. 核心认知：Obsidian 账号 ≠ 同步
2. 电脑端安装 Obsidian（Ubuntu/Debian）
3. 本地 Git 仓库 + 创建私有远程
4. 关键一步：.gitignore 处理 workspace.json
5. 手机端接入：Obsidian Git 插件
6. 附件管理：ref/ 目录与图片引用
7. 踩坑记录
8. 多端协作规范

1. 核心认知：Obsidian 账号 ≠ 同步

这是新手最容易误解的地方：

> 登录 Obsidian 账号 ≠ 同步笔记。

Obsidian 的笔记是纯本地 Markdown 文件，软件本身没有云端存储。你注册的 obsidian.md 账号只解锁两个付费功能：

Obsidian Sync（约 $4/月）— 官方端到端加密同步
Obsidian Publish — 把笔记发布成网站

不付费想多端同步？用 Git。笔记是普通文件，Git 天然适配：版本历史、云端备份、多端同步三件事一次搞定，而且免费。

2. 电脑端安装 Obsidian（Ubuntu/Debian）

推荐用官方 .deb 包安装，自动注册桌面菜单、图标、并支持后续自动更新：


# 到 GitHub Releases 找到最新版本号（示例 v1.13.x）
curl -sL -o /tmp/obsidian.deb \
  https://github.com/obsidianmd/obsidian-releases/releases/download/v1.13.x/obsidian_1.13.x_amd64.deb

# 安装

sudo dpkg -i /tmp/obsidian.deb

rm -f /tmp/obsidian.deb

安装后启动 Obsidian，选择 Open folder as vault（把文件夹作为仓库），指向你的笔记目录（本文以 ~/notes 为例）。vault 里自动生成的 .obsidian/ 目录保存外观、快捷键、插件等配置。

3. 本地 Git 仓库 + 创建私有远程

把笔记目录初始化为 Git 仓库，并在 GitHub 上建一个 private 仓库做远端：


cd ~/notes
git init -b main
git add -A
git commit -m "初始化笔记仓库"

# 用 gh CLI 一条命令：创建私有仓库 + 设置 remote + 推送

gh repo create notes --private --source=. --remote=origin --push

remote 建议用 SSH（更安全，不需要在 URL 里带凭据）：


git remote set-url origin [email protected]:<username>/notes.git

> 笔记仓库务必用 private，尤其当笔记里包含账号、地址等隐私内容时。

4. 关键一步：.gitignore 处理 workspace.json

这是整个方案里最容易踩、也最关键的坑。

Obsidian 每次开关界面、移动窗口都会改写 .obsidian/workspace.json（记录当前打开的标签页、窗口布局）。如果不管它：

每次打开笔记都产生一个噪音 commit，git 历史全是垃圾
多端同步时，两端各写各的 workspace.json，频繁合并冲突

正确的 .gitignore：


# Obsidian 工作区状态（频繁变化，忽略）
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# 缓存

.obsidian/cache

.obsidian/ 下其它配置（app.json、appearance.json、core-plugins.json）是稳定的，正常提交同步——这样换设备后连设置都是同一套。

5. 手机端接入：Obsidian Git 插件

手机端装 Obsidian Git（社区插件，作者 Vinzent03，本插件的下载量、维护活跃度都是社区第一梯队）。注意：所有社区插件都没有官方人工审核，筛选标准：只看下载量大、近期更新、GitHub 开源可审计的。

手机端插件有几个与电脑端不同的关键点：

5.1 认证方式：HTTPS + Token（不支持 SSH）

手机端 Obsidian Git 底层用的是 isomorphic-git（纯 JS 实现的 Git），不支持 SSH，必须走 HTTPS + Personal Access Token。

GitHub 创建 Fine-grained PAT 时，权限要选对：

权限	作用	需要吗
Contents: Read and write	读写仓库文件（clone/pull/push 全靠它）	✅ 必选
Administration	仓库管理（改名/删库等）	❌ 别选，权限过大

5.2 配置步骤

手机 Obsidian 新建一个空 vault
设置 → 第三方插件 → 启用社区插件 → 安装 Obsidian Git
插件设置里填：

Username：GitHub 用户名

Password：刚创建的 PAT
命令面板（笔记区单指下滑打开）→ 运行 "Clone an existing remote repo" → 粘贴 https://github.com/<username>/notes.git
提示 .obsidian 冲突时选 YES（让远端配置覆盖）
重启后重新填一遍 Username/PAT（clone 会覆盖工作区）
设置 Author name / Author email——必须和电脑端 git 的 user.name / user.email 一致，否则报错：

> git author name and email are not set

5.3 日常同步

手机改完：命令面板 → "Obsidian Git: Create backup"（提交 + 推送一步完成）
想全自动：插件设置开 Auto pull/push，间隔建议 15 分钟以上（省电）
电脑端：cd ~/notes && git pull，或让 Claude Code 代劳

6. 附件管理：ref/ 目录与图片引用

笔记里的图片、视频、PDF、GPS 轨迹统一放 ref/ 子目录，与正文分离、随 git 管理：


~/notes/
├── 笔记.md
└── ref/
    ├── images/    # 图片（粘贴附件默认落位这里）
    ├── videos/    # 视频
    ├── pdf/       # PDF 文档
    └── gps/       # GPX/KML 轨迹

在 Obsidian 设置中把 附件默认位置 指向 ref/images/（写进 .obsidian/app.json 的 attachmentFolderPath），粘贴的图片自动落位。

图片引用两种语法（区别很实用）：


![[ref/images/photo.jpg]]                # 内嵌显示：阅读时直接看到图片
[[ref/images/photo.jpg|点击查看图片]]      # 链接样式：正文只显示文字，点击才弹出图片

路径相对 vault 根目录，就是相对路径。点开图片后按 Ctrl+Alt+← 或左上角返回箭头即可回到正文。

> 大文件警告： 视频会让 git 仓库迅速膨胀（几 MB 的视频刷屏）。小图片没问题；大视频建议排除在同步外或用 Git LFS。

7. 踩坑记录

坑 1：pull 不会恢复本地未提交的删除

症状：在手机删了一行内容没推送，电脑上 pull 后"没变化"，删掉的内容没回来。原因：Git 是"提交/推送/拉取"模型，不是网盘镜像。pull 只应用远端的提交，绝不会覆盖本地未提交的改动——远端那份文件其实还在，内容没丢。解决：要恢复，用 git restore（放弃本地改动）而不是 pull：


git restore 常用账号信息.md      # 恢复到上次提交状态
# git 2.23 以前用：git checkout -- <文件>

坑 2：手机端报 "author name and email are not set"

手机端克隆后没有 git 全局配置，必须在 Obsidian Git 插件设置里填 Author name / email，且与电脑端一致，否则 push 报错。

坑 3：git 与网盘同步叠加

不要把 git 仓库目录再放到坚果云 / OneDrive / iCloud 等网盘同步文件夹里——两套同步同时操作 .git，会损坏仓库（对象损坏、提交丢失）。同步方式只能二选一。

坑 4：.gitignore 没写好导致噪音 commit

见第 4 节，workspace.json 不忽略的话，git 历史会被 Obsidian 的窗口状态刷屏，多端还冲突。

8. 多端协作规范

先 pull 再 push：任何一端提交推送前，先拉取远端最新，避免冲突
不要双端同时编辑同一个文件：同一时间只在一台设备改，改完推送后再换端
提交消息写清楚：一眼能看出这次改了什么（Obsidian Git 的自动备份会生成 vault backup: 时间戳 格式，可接受）
敏感内容慎入云端：即使 private 仓库，推上去就永久留在 git 历史里，删了文件历史仍在；银行卡号、身份证号这类信息建议不入库或单独加密

总结

这套方案的核心价值在于：笔记本质是文件，Git 就是最成熟的文件版本管理工具。用 git init + private remote + 手机端插件 三件套，就得到了一套免费、可审计、有完整版本历史的个人知识库同步系统。配合 ref/ 附件目录和图片引用语法，Obsidian 的多媒体笔记也能和正文一起无缝流转于设备之间。

> 关联文章：Ubuntu XFCE 桌面环境完整配置指南