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 文件。

初次使用建议：

• 新建一个专门存放笔记的本地文件夹。
• 在 Obsidian 中选择“打开本地仓库”或“Open folder as vault”。
• 后续所有笔记都放进这个文件夹，方便统一备份和同步。
• 不要把笔记散落在多个临时目录里，否则后面接 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，并将仓库克隆到本地

推荐方式：

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

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

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

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

之后：

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

4.3. 忽略文件管理

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

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

1234/.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 分钟左右，观察右上角同步提示。
• 打开 GitHub 网页端，确认文件已经更新。
• 再从 GitHub 网页端新建或修改一个测试文件。
• 重新打开 Obsidian，确认本地是否拉取到远程修改。

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

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

5.1. AI接入

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

本地 Markdown 文件的优势：

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

Gemini CLI 示例流程：

• 安装 Node.js。
• 在终端安装 Gemini CLI。

1npm install -g @google/gemini-cli

• 登录 Gemini。

1gemini login

• 进入笔记库目录，让 AI 在当前目录内工作。

1cd D:\your-notes-vault
使用时要明确范围，例如：

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

5.2. 双向链接和图谱

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

常用语法：

12[[笔记标题]][[笔记标题|显示文本]]
使用建议：

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

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

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

5.3. 实用场景

• 从旧内容里产出新内容

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

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

示例：

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

• 批量整理目录和文件

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

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

示例：

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

• 搜资料并起草内容

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

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

示例：

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

• 模仿个人文风写作

如果笔记库中已有大量自己的文章、脚本或教程，可以让 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
这样做的好处是，笔记和附件之间的关系更清楚，未来迁移、导出或发布博客时也更稳定。

6.4. Obsidian 原生设置改动

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

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

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

6.5. 最终效果

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

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

七、打通手机端同步

7.1. 基础步骤

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

基础流程：

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

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

7.2. Git 同步配置

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

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

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

7.3. Token 获取路径

GitHub Token 获取路径：

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

注意事项：

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

冲突处理原则：

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

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