Obsidian 笔记使用全攻略

再次特别感谢技术爬爬虾的课程。

我们学的不是单个软件，而是一整套可以长期沉淀知识资产的工作流。
结合 AI，可以提高知识整理、内容生产和资料复用的效率。
最后把这套内容沉淀成真正能长期迁移、备份、协作和复用的知识资产。

我们关心的不是“某个按钮在哪里”，而是怎么把笔记、知识沉淀、多端同步、版本管理和 AI 协作真正串起来，让 Obsidian 不只是一个写字软件，而是自己的本地知识中台。

一、开场白

1.1. 教程主要内容

  • 理解为什么长期选择 Obsidian：它更适合沉淀可迁移的知识资产。
  • 知道怎么把 Obsidian 接上 GitHub，获得免费同步、云端备份和版本管理。
  • 知道怎么通过 Obsidian Git 插件降低手动同步成本。
  • 知道图片、附件、链接和导出如何标准化，避免笔记库后期变乱。
  • 知道手机端如何接入同一个笔记库，并理解 Git 冲突风险。
  • 知道怎么把 Gemini CLI、Claude Code、Codex 等 AI 工具接进本地笔记工作流。
  • 知道这套方案的边界：GitHub 不是唯一备份，AI 不是完全自动驾驶，版本控制才是安全网。

这篇教程的定位是“先能稳定用起来，再逐步增强”。前期重点是把本地文件、同步和备份打稳；后期再把 AI、双向链接、图谱和内容生产接进来。

二、Obsidian工具

2.1. Obsidian笔记工具的优势

2.1.1. 数据在自己手里

Obsidian 的核心优势，是笔记默认存成电脑上的独立 Markdown 文件。

  • 文件存在本地，不被单一平台锁死。
  • 即使 Obsidian 停止维护，也可以用 VS Code、Typora、Notepad++ 等 Markdown 编辑器继续打开。
  • Markdown 是纯文本格式，适合长期保存、搜索、迁移和版本管理。
  • 配合 Git 后，每次修改都能留下历史记录，出错时可以回退。

笔记理解：

Obsidian 不是把知识托管给某个平台，而是把知识资产放回自己手里。

2.1.2. 用起来更顺

笔记工具的流畅度会直接影响心流。卡顿、白屏、切换延迟，看起来是小问题，长期写作时会不断打断注意力。

Obsidian 的体验优势主要体现在：

  • 笔记切换速度快。
  • 本地文件读写稳定。
  • 窗口操作和搜索响应更轻。
  • 大量笔记长期积累后，也更容易保持可控。

这点很适合结合个人体验来讲：好的笔记工具不应该在写作时抢存在感，而应该像纸和笔一样稳定。

2.1.3. 更容易和 AI 配合

Obsidian 的本地 Markdown 文件天然适合 AI 工具处理。

  • AI 编程工具擅长读写本地文件。
  • Markdown 结构清晰，标题、列表、代码块都容易被模型理解。
  • Git 可以记录 AI 修改前后的差异，方便审查和回滚。
  • 本地笔记库可以成为 AI 的长期上下文，让 AI 帮忙查找、整理、改写和生成内容。

典型协作方式：

  • 让 AI 搜索旧笔记，整理某个主题的资料。
  • 让 AI 按现有文风改写文章。
  • 让 AI 批量整理目录和文件命名。
  • 让 AI 根据过往内容生成选题、脚本、教程初稿。

2.2. Obsidian工具下载安装

2.2.1. 网络环境

下载 Obsidian、访问 GitHub、安装部分 AI 工具时，可能需要更稳定的网络环境。后续使用 Gemini CLI、Claude Code 等工具，也可能涉及外部账号登录和命令行授权。

可参考：AI工具安装使用教程

2.2.2. 下载官网

Obsidian 官网：

https://obsidian.md

下载安装时按自己的系统选择 Windows、macOS 或 Linux 版本即可。

2.2.3. 安装配置

安装完成后，最重要的是理解两个概念：

  • Vault（仓库/库）：Obsidian 管理的一整个笔记文件夹。
  • Markdown 文件：每一篇笔记本质上就是一个 .md 文件。

初次使用建议：

  1. 新建一个专门存放笔记的本地文件夹。
  2. 在 Obsidian 中选择“打开本地仓库”或“Open folder as vault”。
  3. 后续所有笔记都放进这个文件夹，方便统一备份和同步。
  4. 不要把笔记散落在多个临时目录里，否则后面接 Git 和 AI 会变麻烦。

三、扩展生态工具

3.1. AI 工具

可以和 Obsidian 配合的 AI 工具有很多，重点不是追求工具数量，而是让它们能稳定处理本地 Markdown 文件。

  • Gemini CLI：适合命令行批量处理笔记、生成选题、整理目录。
  • Claude Code：适合结合本地项目和文档做较复杂的读写协作。
  • Codex：适合代码、文档、知识库整理和本地文件修改。

可参考：AI工具安装使用教程

使用原则：

  • 让 AI 在明确范围内改文件，不要一次让它改整个笔记库。
  • 重要修改先看 Git diff，再决定是否保留。
  • 涉及事实、价格、政策、技术版本的信息，要额外校验。
  • AI 更适合做整理、归纳、初稿和批处理，最终判断仍然要由人负责。

3.2. 插件和辅助工具

常用扩展工具：

  • Watt Toolkit：GitHub 网速太慢或打不开时，用来改善访问体验。
  • Git：版本控制基础工具，是同步和回滚的底层能力。
  • GitHub Desktop：适合不熟悉命令行的用户，可视化提交、推送、拉取笔记。
  • Obsidian Git：Obsidian 内部自动提交、拉取和推送的插件。
  • Custom Attach Location：统一图片和附件存储位置。
  • Pandoc：配合导出插件，把 Markdown 导出为 Word、HTML 等格式。

插件使用建议：

  • 插件不要一次装太多，先围绕真实需求安装。
  • 同步、附件、导出属于基础增强，可以优先配置。
  • 主题美化类插件可以后置，避免一开始把时间花在外观折腾上。

3.3. Markdown语法和导出能力

Obsidian 的底层是 Markdown，因此先掌握常用语法会更稳。

功能 语法 用途
标题 # 一级标题、## 二级标题 建立文章层级
加粗 **重点内容** 标记关键概念
引用 > 引用内容 摘录观点、放提示
无序列表 - 项目 整理要点
有序列表 1. 步骤 写操作教程
代码块 三个反引号包裹代码 保存命令、配置、代码
删除线 ~~过时内容~~ 标记废弃信息
高亮 ==重点== 在 Obsidian 内突出重点

导出方面，可以安装 Enhancing Export 这类插件，并配置 Pandoc。适合把笔记导出为：

  • Word 文档。
  • HTML 页面。
  • PDF 或其他归档格式。

注意：导出能力属于锦上添花，核心仍然是把 Markdown 源文件管理好。

四、免费云同步搭建步骤

目标：

  • 解决 Obsidian 默认没有原生免费同步的问题。
  • 让笔记同时具备同步、备份、版本管理能力。
  • 让 AI 修改笔记时有可追踪、可回滚的安全网。

这里不是把 GitHub 当普通网盘，而是把它当同步中枢和版本中心。

4.1. 核心工具安装

需要准备：

  • Obsidian：负责编辑和管理笔记。
  • GitHub：负责远程仓库和云端备份。
  • Git：负责版本控制。
  • GitHub Desktop：负责可视化提交、推送、拉取。

如果刚开始不熟悉命令行，可以先用 GitHub Desktop。等理解 Git 基本逻辑后，再逐步学习命令行操作。

4.2. 搭建详细步骤

4.2.1 注册并登录 GitHub

访问 GitHub 官网注册账号并登录。如果访问速度慢，可以先尝试改善网络，或使用 GitHub Desktop 处理本地同步。

4.2.2 新建仓库并设成 private

在 GitHub 中点击 New repository 创建仓库。

建议配置：

  • 仓库名使用英文或拼音，避免后续工具兼容问题。
  • Visibility 设置为 Private，避免私人笔记公开。
  • 初学时可以先不勾选复杂模板，保持仓库干净。

笔记库可能包含私人资料、账号信息、草稿想法和未公开内容，所以私有仓库是基础要求。

4.2.3 安装 Git，并将仓库克隆到本地

推荐方式：

  1. 安装 Git。
  2. 安装 GitHub Desktop。
  3. 在 GitHub Desktop 中选择 File → Clone repository。
  4. 选择刚创建的私有仓库。
  5. 指定本地存储路径。

克隆完成后，本地会出现一个与 GitHub 仓库关联的文件夹。这个文件夹就是后续 Obsidian 的 Vault。

4.2.4 在 Obsidian 里打开这个本地文件夹

打开 Obsidian，选择“打开本地仓库”或“Open folder as vault”，再选择刚刚克隆到本地的文件夹。

之后：

  • 新建笔记会生成 .md 文件。
  • 修改笔记会体现为 Git 文件变更。
  • 提交和推送后，GitHub 云端会保存对应版本。

4.3. 忽略文件管理

不要所有文件都直接进入 Git。某些文件记录的是本地界面状态，经常变化，容易制造无意义提交或冲突。

建议在仓库根目录创建 .gitignore，加入类似配置：

1
2
3
4
/.obsidian/workspace.json
/.obsidian/workspace-mobile.json
/.trash/
/.upcd

说明：

  • workspace.json 通常记录当前打开的标签页、布局等工作区状态。
  • 手机端和电脑端的工作区配置可能不同，混在一起容易冲突。
  • .trash 这类临时目录通常不需要同步。
  • 参考教程里提到的 /.upcd 也可以按实际情况排除。

.gitignore 要尽早处理。越早排除高频变化文件，后续同步越干净。

4.4. 同步自动化

自动化不是为了“省一步操作”，而是为了降低长期维护成本。

4.4.1 插件部署

进入 Obsidian 设置，找到第三方插件相关入口。

4.4.2 打开第三方插件

如果首次使用第三方插件，需要先允许安装社区插件。

4.4.3 关闭安全模式

关闭安全模式后才能搜索和安装社区插件。安装插件时优先选择下载量高、维护活跃、评价稳定的插件。

4.4.4 安装 Obsidian Git

搜索 Obsidian Git，安装并启用。它可以在 Obsidian 内自动完成提交、拉取和推送。

4.4.5 关键配置

推荐配置：

  • 开启 Auto commit and push after stopping file edits。
  • Minutes after stopping edits 设置为 1 分钟左右。
  • 开启 Pull on startup，启动时自动拉取远程更新。
  • 自动提交信息可以设置成固定格式，例如 vault backup: {{date}}，方便识别。

演示验证：

  1. 在本地新建一篇测试笔记。
  2. 输入几行内容并保存。
  3. 等待 1 分钟左右，观察右上角同步提示。
  4. 打开 GitHub 网页端，确认文件已经更新。
  5. 再从 GitHub 网页端新建或修改一个测试文件。
  6. 重新打开 Obsidian，确认本地是否拉取到远程修改。

GitHub 很重要，但不是唯一备份。GitHub 负责日常同步和版本记录，网盘、移动硬盘或 NAS 负责额外容灾。真正目标不是“有同步”，而是“更不容易丢”。

五、AI 全面接入，智能协作

5.1. AI接入

Obsidian 接入 AI 的关键，不一定是在 Obsidian 里安装 AI 插件，而是让 AI 工具能直接处理本地笔记目录。

本地 Markdown 文件的优势：

  • AI 能读懂标题、列表、表格和代码块。
  • AI 能批量搜索、归类和改写文件。
  • Git 能记录 AI 修改前后的差异。
  • 不满意可以回滚，降低试错成本。

Gemini CLI 示例流程：

  1. 安装 Node.js。
  2. 在终端安装 Gemini CLI。
1
npm install -g @google/gemini-cli
  1. 登录 Gemini。
1
gemini login
  1. 进入笔记库目录，让 AI 在当前目录内工作。
1
cd D:\your-notes-vault

使用时要明确范围，例如：

1
gemini "请根据 2024-2025 年的视频脚本笔记，整理 10 个新选题，输出到 未来选题.md"

5.2. 双向链接和图谱

双向链接的价值，不是为了让图谱看起来复杂，而是主动建立知识之间的关系。

常用语法：

1
2
[[笔记标题]]
[[笔记标题|显示文本]]

使用建议：

  • 在概念第一次出现时链接到对应笔记。
  • 在项目复盘中链接相关资料、会议记录和决策文档。
  • 在教程类文章中链接前置知识和后续延伸阅读。
  • 不要为了连而连，链接应该帮助未来的自己更快找到上下文。

图谱是双向链接的可视化结果。链接积累得越多，越容易看到内容之间的新连接，也更容易从旧笔记中长出新选题。

图片和附件最好一开始就标准化，否则笔记库变大后再整理会很痛苦。

5.3. 实用场景

  1. 从旧内容里产出新内容

可以让 AI 读取某个主题下的旧笔记，整理成：

  • 博客文章。
  • 视频选题。
  • 课程大纲。
  • FAQ。
  • 知识卡片。

示例：

1
gemini "参考 随手记 目录下关于 Obsidian 的笔记，整理一篇面向新手的使用教程，输出为 Obsidian使用教程草稿.md"
  1. 批量整理目录和文件

AI 适合做重复性的文件整理：

  • 自动创建目录。
  • 自动拆分文件夹。
  • 自动迁移对应内容。
  • 自动清理临时文件。
  • 批量统一命名风格。

示例：

1
gemini "请把 未来选题.md 中的 10 个选题分别创建子文件夹，并在每个文件夹里生成一个 大纲.md"
  1. 搜资料并起草内容

可以让 AI 先参考已有笔记，再生成一个可继续加工的初稿：

  • 先限定参考目录。
  • 再限定输出格式。
  • 最后要求列出待人工确认的信息。

示例：

1
gemini "请参考 教程 和 随手记 目录中关于 AI 工具的内容，整理一份 AI 工具安装使用教程提纲，并标出需要人工确认的部分"
  1. 模仿个人文风写作

如果笔记库中已有大量自己的文章、脚本或教程，可以让 AI 提取风格特征，再按同样风格写初稿。

注意：模仿文风适合加速初稿，但最后仍需要人工判断内容是否准确、表达是否自然。

AI 可以帮忙，但不能完全代替人工判断。前面已经用 Git 把整个仓库接住了，AI 改动可查看差异，不满意就能回滚。Git 在这里不仅是同步工具，它还是 AI 参与知识管理时的安全网。

六、图片和附件命名规范化

6.1. 默认方案的问题

Obsidian 默认图片和附件处理方式能用，但长期积累后容易出现问题：

  • 图片容易散落在笔记同级目录，文件夹变乱。
  • 附件命名不统一，后续迁移和查找困难。
  • 如果使用 Obsidian Wiki 链接，某些第三方编辑器或 GitHub 预览不一定能稳定识别。
  • 图片和笔记没有形成固定对应关系，删除或移动笔记时容易漏掉附件。

6.2. 解决思路

安装 Custom Attach Location，把附件存储、命名、引用全部标准化。

目标效果：

  • 每篇笔记的图片放到独立附件目录。
  • 图片路径使用标准 Markdown 相对路径。
  • 图片文件自动重命名，减少重复和乱码。
  • 在 VS Code、GitHub 网页端、其他 Markdown 工具里也能正常预览。

6.3. 重点配置

推荐配置思路：

  • Markdown URL 格式使用类似：./assets/${noteTitle}/${filename}。
  • 开启附件自动重命名。
  • 粘贴图片后自动进入当前笔记对应的 assets 子目录。
  • 尽量使用英文、数字、短横线或下划线命名附件。

示例效果：

1
![示例图片](/assets/Obsidian使用教程/example-image.png)

这样做的好处是，笔记和附件之间的关系更清楚，未来迁移、导出或发布博客时也更稳定。

6.4. Obsidian 原生设置改动

建议同步调整 Obsidian 原生设置：

  • 关闭“使用 Wiki 链接”。
  • 内部链接类型选择“基于当前笔记的相对路径”。
  • 新附件默认存放位置按插件规则统一管理。

关闭 Wiki 链接后，链接更接近标准 Markdown，兼容性更好。

6.5. 最终效果

完成后，笔记库会更适合长期维护：

  • 自动生成 assets 目录。
  • 目录结构更整洁。
  • 图片引用更标准。
  • 文件改名和迁移时更容易排查问题。
  • GitHub、VS Code 和其他 Markdown 工具中更容易正常渲染。

七、打通手机端同步

7.1. 基础步骤

手机端接入的目标，是让同一个 Obsidian Vault 能在手机上查看和编辑。

基础流程：

  1. 用数据线连接手机和电脑。
  2. 手机选择“传输文件”模式。
  3. 将电脑端笔记库完整复制到手机的 Documents 或其他固定目录。
  4. 打开手机端 Obsidian。
  5. 选择 Open folder as vault。
  6. 选择刚复制过去的笔记文件夹。
  7. 如果提示信任作者，确认后进入笔记库。

第一次配置建议先只验证能否正常打开和搜索笔记，不要立刻在手机端大量修改。

7.2. Git 同步配置

手机端要和 GitHub 同步，需要配置：

  • GitHub 用户名。
  • GitHub 注册邮箱。
  • Personal Access Token。
  • 远程仓库地址。

配置完成后，手机端也可以执行拉取和推送。不同插件或系统界面可能略有差异，核心都是让手机端具备访问私有仓库的权限。

7.3. Token 获取路径

GitHub Token 获取路径：

  1. 打开 GitHub 网页端。
  2. 进入 Settings。
  3. 进入 Developer settings。
  4. 进入 Personal access tokens。
  5. 选择 Tokens (classic) 或 GitHub 当前推荐的细粒度 token。
  6. 创建新 token。
  7. 勾选 repository 相关权限。
  8. 复制 token，粘贴到手机端同步配置里。

注意事项：

  • Token 只会完整显示一次，要及时保存到安全位置。
  • 不要把 token 写进公开笔记或公开仓库。
  • 如果怀疑泄露，立刻在 GitHub 中撤销旧 token 并重新生成。
  • 手机和电脑不要同时编辑同一篇内容，否则容易触发 Git 冲突。

冲突处理原则：

  • 如果出现冲突，先不要继续大量编辑。
  • 回到电脑端查看 Git 变更。
  • 保留正确版本后再提交。
  • 不确定时先复制一份冲突文件做备份。

最后再强调一遍：GitHub 同步不是唯一备份。重要笔记建议定期复制到本地硬盘、移动硬盘、NAS 或网盘中，形成多重备份。日常同步靠 GitHub，长期容灾靠额外冷备份。