Obsidian 配置 Git 插件实现笔记同步到 GitHub（Mac 版）

通过配置 Obsidian Git 插件可将本地笔记版本化并同步至 GitHub，便于多设备管理及 AI 模型读取。主要步骤包括安装 Git 插件、初始化仓库、绑定远程地址、提交更改及配置.gitignore 排除缓存文件，确保同步内容纯净且避免冲突。

字节跳动发布于 2026/3/21更新于 2026/6/2631 浏览

背景

近期在探索 AI Agent 应用时，发现需要让大模型能访问本地笔记数据。利用 Obsidian 配合 GitHub 私有库是个不错的方案，既能版本控制又能云端备份。这里记录下在 Mac 环境下的具体配置经验。

前置准备

确保本地已安装 Obsidian 和 Git 工具。检查 Git 是否可用，可在终端输入 git --version 确认。

类型	名称
操作系统	macOS (非移动端)
Obsidian 版本	1.10.6

安装插件

打开 Obsidian，点击左下角设置图标进入设置页面。

Obsidian 设置入口

开启安全模式后，点击'浏览插件市场'，搜索'Git'并确认安装。建议安装名为 obsidian-git 的官方插件。

插件搜索结果

安装完成后，重启 Obsidian 即可看到插件生效。

插件启用状态

仓库初始化与关联

初始化本地仓库

按下快捷键 Cmd + P 唤起命令面板，输入 Git: Initialize a new repo 进行初始化。

初始化成功后，再次通过 Cmd + P 输入 Git: Open source control view，若能看到类似结构说明初始化完成。

源控制视图

绑定 GitHub 远程地址

同样使用 Cmd + P，搜索 Git: Edit remotes。

Remote name 选择 origin
URL 格式填写：https://github.com/你的用户名/你的仓库名.git

编辑远程地址

接着设置上游分支，搜索 Git: Set upstream branch，选择 origin/main。这一步只需执行一次。

提交与同步

方式一：命令行操作

在命令面板搜索 Git: Commit all changes，输入提交信息后确认。

提交更改

方式二：手动推送

也可以通过界面按钮手动提交并推送到远程仓库。

手动提交

推送成功

进阶配置：优化同步策略

为了避免上传无用的缓存文件导致冲突，建议配置 .gitignore。

在 Obsidian 中通过 Cmd + P 调用指令创建或编辑 .gitignore 文件，填入以下内容：

############################# Obsidian - 必须忽略（强烈推荐）#############################
# 工作区状态（窗口/当前文件/布局，多设备必冲突）
.obsidian/workspace
.obsidian/workspace.json
# 缓存文件（无价值，可再生）
.obsidian/cache/
.obsidian/index.db
.obsidian/index.db-shm
.obsidian/index.db-wal
############################# Obsidian - 可选忽略#############################
# 同步/发布相关（你不用官方 Sync/Publish 可忽略）
.obsidian/graph.json
.obsidian/appearance.json
############################# 系统垃圾#############################
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
############################# 编辑器/临时文件#############################
*.tmp
*.temp
*.bak
*.swp
*.swo
############################# 日志#############################
*.log

这样配置后，同步到 GitHub 的内容将更纯净，也能有效避免多设备间的文件冲突问题。

背景