用 Obsidian 给 Claude Code 装上本地知识库：30分钟从零搭建
你用 Claude Code 写代码时，有没有遇到过这些问题：
- “帮我重构这个模块”——但 Claude Code 不知道你项目的架构决策历史
- “这个 API 的调用规范是什么？”——答案散落在三份不同的文档里
- “上次我们讨论的方案结论是什么？”——翻了一堆聊天记录也找不到
Claude Code 很强，但它每次对话都是"失忆"的。它不知道你的项目经历了什么决策、踩过什么坑、积累过什么经验。
解决方法很简单：建一个本地知识库，让 Claude Code 每次启动都能"读取你的记忆"。
本文用 3 步完成：Obsidian 搭建知识库 → obsidian-markitdown 插件导入现有文档 → 配置 CLAUDE.md 让 Claude Code 自动读取。
一、整体思路
┌─────────────────────────────────────────────┐
│ Claude Code（编码时） │
│ 启动时自动读取 CLAUDE.md + 项目知识库 │
├─────────────────────────────────────────────┤
│ Obsidian（知识管理） │
│ Markdown 文件 + 双向链接 + 标签检索 │
├─────────────────────────────────────────────┤
│ obsidian-markitdown（导入） │
│ Word/Excel/PPT/PDF → Markdown 一键转换 │
└─────────────────────────────────────────────┘
核心逻辑：Claude Code 启动时会自动读取项目目录下的 CLAUDE.md 文件。你只需要把知识库放在项目目录里，在 CLAUDE.md 中告诉 Claude Code 去哪里找信息。
二、Obsidian 知识库搭建
2.1 安装
| 平台 | 安装方式 |
|---|---|
| Windows | 官网下载 .exe 安装包，或 winget install Obsidian.Obsidian |
| macOS | 官网下载 .dmg，或 brew install --cask obsidian |
| Linux | 官网下载 .AppImage，或 sudo snap install obsidian --classic |
下载地址：obsidian.md
2.2 创建知识库
安装后打开 Obsidian → “创建新库（Create new vault）” → 选择一个本地文件夹作为存储路径。
Vault 本质上就是一个普通文件夹，里面全是 .md 文件。用任何文本编辑器都能打开，Claude Code 也能直接读取。
2.3 文件夹结构设计
knowledge-base/
├── 00-Inbox/ # 待整理的素材
├── 01-Architecture/ # 架构决策记录（ADR）
├── 02-APIs/ # API 文档、接口规范
├── 03-TechNotes/ # 技术调研笔记
├── 04-Solutions/ # 问题解决方案、踩坑记录
├── 05-References/ # 参考资料
└── CLAUDE.md # Claude Code 配置（关键！）
2.4 必装插件
在 Obsidian → Settings → Community Plugins → Browse 中搜索安装：
| 插件 | 用途 |
|---|---|
| Markitdown | Office 文档转 Markdown（核心） |
| Dataview | 用 SQL 语法查询笔记库 |
| Templater | 高级模板，自动填充日期、标签 |
三、导入现有文档：obsidian-markitdown 插件
你手头可能已经有大量 Word、Excel、PPT 格式的技术文档、方案评审、API 规范。用 obsidian-markitdown 插件可以在 Obsidian 内直接转换，不需要打开终端。
3.1 安装插件
- Obsidian → Settings → Community Plugins → Browse → 搜索 Markitdown → Install → Enable
- 插件会自动检测 Python 环境。如果没有 Python：
| 平台 | 安装 Python |
|---|---|
| Windows | winget install Python.Python.3.12 或从 python.org 下载 |
| macOS | brew install python@3.12 或从官网下载 |
| Linux | sudo apt install python3 python3-pip（Ubuntu/Debian） |
- 首次启用插件时会提示安装 markitdown Python 包，点确认即可
底层调用的是微软官方的 markitdown 工具，专为 Office 格式优化。
3.2 支持的格式
| 格式 | 说明 |
|---|---|
| Word (.docx) | 微软自家解析，格式保留最完整 |
| Excel (.xlsx / .xls) | 直接输出 Markdown 表格 |
| PowerPoint (.pptx) | 提取幻灯片结构+文本 |
| 内置解析，支持 OCR 提取图片文字 | |
| 图片 | 自动 OCR 提取图片中的文字 |
| HTML / CSV / JSON / XML | 文本类格式直接转换 |
3.3 使用方式
单个文件： 命令面板（Ctrl+P / Cmd+P）→ 「Convert file to Markdown with Markitdown」→ 选择文件 → Convert
拖拽： 直接把文件从文件管理器拖进 Obsidian 编辑器，自动转换并插入链接
整个文件夹： 命令面板 → 「Convert folder to Markdown」→ 选择文件夹 → 勾选「Include subfolders」→ Convert
3.4 推荐设置
在 Settings → Markitdown 中建议调整：
- Output Folder：改为
00-Inbox - Auto Frontmatter：打开，自动添加 YAML 元数据
- Auto Tags：填入常用标签，如
import, reference - Extract Images：打开，自动提取嵌入图片
四、让 Claude Code 读取你的知识库
知识库搭好了，关键一步：让 Claude Code 知道这些知识的存在。
4.1 CLAUDE.md 配置文件
在知识库根目录（也就是你的项目目录）创建 CLAUDE.md：
# 项目知识库
## 知识库位置
项目技术知识库位于 `knowledge-base/` 目录，包含架构决策、API 文档、技术调研和解决方案。
## 知识库结构
- knowledge-base/01-Architecture/ — 架构决策记录，每个决策一个文件
- knowledge-base/02-APIs/ — API 接口文档和调用规范
- knowledge-base/03-TechNotes/ — 技术调研笔记
- knowledge-base/04-Solutions/ — 踩坑记录和解决方案
## 使用规则
- 涉及架构决策时，先查阅 01-Architecture/ 了解历史决策背景
- 编写 API 调用代码时，参考 02-APIs/ 中的规范
- 遇到技术选型问题，先看 03-TechNotes/ 是否已有调研
- 遇到 bug 或报错，先查 04-Solutions/ 是否有记录
Claude Code 启动时会自动读取这个文件。当你问它问题时，它会根据指引去查阅相关文档。
4.2 实际效果对比
没有知识库时：
> 帮我写一个调用支付接口的函数
Claude Code 会基于通用知识写一个"看起来对的"函数——但它不知道你们用的是支付宝还是微信支付，不知道签名规则，不知道回调地址配置在哪。
有知识库时：
> 帮我写一个调用支付接口的函数
Claude Code 会自动去 02-APIs/ 查阅你们项目的支付接口文档，写出符合你们规范的代码——包括正确的签名算法、错误处理、回调格式。
4.3 知识库该放什么
不是所有东西都需要进知识库。推荐只放会反复被查阅、影响编码决策的信息：
| 放进知识库 | 不需要放 |
|---|---|
| 架构决策记录（为什么选A不选B） | 临时调试日志 |
| API 接口规范和调用示例 | 一次性运行的脚本 |
| 技术选型调研结论 | 已过时的方案 |
| 踩坑记录和解决方案 | 代码本身（Claude Code 能直接读） |
| 业务规则说明 | 聊天记录 |
关键原则：放结论和决策，不放过程和流水账。
五、日常维护：让知识库保持有用
知识库最怕的不是"建不起来"，而是"建了没人用"。两个习惯让知识库持续产生价值：
习惯一：踩坑后立即记录
在 Obsidian 中打开 04-Solutions/，新建一条笔记：
---
title: React Native iOS 打包报错 DT_TOOLCHAIN_DIR
date: 2026-04-27
tags: [react-native, ios, build]
---
## 问题
React Native 打包 iOS 时报错 DT_TOOLCHAIN_DIR cannot be used to evaluate PRODUCT_BUNDLE_IDENTIFIER
## 原因
Xcode 版本升级后环境变量变化
## 解决方案
在 Podfile 顶部添加：
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '14.0'
end
end
end
下次 Claude Code 遇到同样的问题，它会直接找到这条记录。
习惯二：重要决策写 ADR
架构决策记录（Architecture Decision Record）是最有价值的知识。模板：
---
title: ADR-005: 状态管理从 Redux 迁移到 Zustand
date: 2026-04-27
tags: [adr, frontend, state-management]
status: accepted
---
## 背景
Redux 在当前项目中导致样板代码过多，新成员上手成本高。
## 决策
迁移到 Zustand，保持 store 结构不变。
## 理由
- 代码量减少约 60%
- TypeScript 类型推断更好
- 学习成本低，API 更直觉
## 影响
- 需要逐步替换现有 23 个 Redux slice
- 中间件（thunk）替换为 Zustand 自带的 async actions
六、总结
| 组件 | 职责 | 成本 |
|---|---|---|
| Obsidian | 本地知识库，编辑和检索 | 免费 |
| obsidian-markitdown | 现有文档一键转 Markdown | 免费 |
| CLAUDE.md | 让 Claude Code 自动读取知识库 | 免费 |
30分钟启动路径：
- 安装 Obsidian → 创建 Vault → 建好文件夹结构
- 安装 Markitdown 插件 → 把现有的技术文档拖进去转换
- 在项目根目录写一个 CLAUDE.md → 告诉 Claude Code 知识库在哪
- 下次用 Claude Code 写代码时，它就能"记住"你的项目知识了
知识库不是写给 AI 看的，是写给你自己看的。只是恰好 Claude Code 也能读懂 Markdown——所以你整理的每一条知识，都在让 AI 写的代码更贴合你的项目。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
11
0- 0
已为社区贡献18条内容
所有评论(0)