你下载好 Obsidian第一次打开软件迎面就是一个英文弹窗Create new vault。很多新手在这里就卡住了。vault 这个词一看就不是普通单词搜索引擎里伴随它出现的往往还有“知识库搭建”“个人信息管理系统”这类让人紧张的说法于是你会误以为要用 Obsidian得先学会一套高深的知识管理哲学。但我要先给出一个判断Vault 在物理世界里就是一个普普通通的文件夹。没有数据库、没有私有格式、没有云端绑定。Obsidian 所做的全部事情就是把这个文件夹里的 Markdown 文件读进来再用双链、标签、图谱这些能力让文件夹“活”起来。理解这一点比记住一百个快捷键都重要也是整个 Obsidian 入门过程中最值得先想明白的事。这篇文章不会讲高深方法论而是从一个最容易被忽略的事实切入Vault 就是文件夹。我会带你从文件管理器视角看 Vault 的目录结构给出创建 Vault 的具体步骤讲解.obsidian隐藏目录、双链和图谱的底层逻辑并讨论多设备同步、常见误区、最佳实践。如果你正被“创建 Vault”这一步卡住或者用 Obsidian 一段时间后总觉得概念很虚这篇文章会帮你把地基打牢。另外说明一个背景Obsidian 社区里大量进阶技巧比如 Dataview、Git、图谱分析、接入 AI 等本质上都在操作文件夹里的纯文本文件。只要你理解了 Vault 的文件夹本质后面学任何插件都会快很多。1. Vault 不是“知识库管理系统”而是一个文件夹1.1 先在文件管理器里证明这件事你可以直接在系统里新建一个文件夹命名为 MyNotes。Windows 用资源管理器macOS 用 FinderLinux 用户用你喜欢的任何文件管理器都可以。然后打开 Obsidian点击界面上的 “Open folder as vault”选中刚才新建的文件夹。Obsidian 会立即进入一个新工作区。此时你回到文件管理器刷新一下会发现 MyNotes 里多了一个名为.obsidian的隐藏文件夹仅此而已。没有自动创建什么数据库文件没有上传你的任何内容到云端也没有强制你选择“笔记格式”。一句话概括Obsidian 打开了一个文件夹并在这个文件夹里放了一些配置文件。如果你习惯用命令行可以先用如下命令创建这个最小 Vaultmkdir -p ~/Documents/MyNotes然后打开 Obsidian通过 “Open folder as vault” 选择~/Documents/MyNotes即可。这个文件夹从这一刻起就成了 Obsidian 语境里的 Vault。1.2 为什么这个设计值得被认真对待传统笔记软件通常把内容存进自己的数据库或云服务器。看起来用户是在写笔记实际上数据被封装在一个“黑盒”里你只能通过软件本身读写迁移时需要专门的导出功能如果软件停止服务数据能不能完整拿回来也是个未知数。Obsidian 走的是完全不同的路线。Vault 里的每一篇笔记都是一个.md文件也就是纯文本 Markdown。你甚至不用 Obsidian 来打开它用 Typora、VS Code、记事本任意一个支持文本编辑的工具都能直接读取和修改。从文件系统的视角看Vault 就是一个普通目录可以被复制、压缩、移动到任何地方。这个设计带来的直接收益有三个第一数据所有权明确。你不需要担心某个云服务关闭后笔记丢失只要文件夹在笔记就在。第二迁移成本几乎为零。想从 Obsidian 换到其他 Markdown 工具直接把文件夹交给新工具就行不需要导入导出。第三外部工具可以参与管理。Git、同步盘、自动化脚本、AI 工具都能直接面向文件夹里的纯文本文件工作不会受制于私有格式。1.3 传统笔记软件与 Obsidian Vault 的对比为了更直观这里用一个表格对比传统笔记应用和 Obsidian Vault对比维度传统笔记应用Obsidian Vault数据存储位置云端或私有数据库本地文件夹文件格式私有格式需要导出转换纯文本 Markdown是否依赖网络多数强依赖本地优先可选同步数据迁移需要导出导入流程直接复制文件夹扩展性受平台限制插件与外部脚本均可操作成本模型通常订阅制本地使用免费Sync/Publish 收费表格里的“本地使用免费”特别值得强调。Obsidian 官方收费的是同步服务 Sync 和发布服务 Publish而不是笔记软件本身。很多新手误以为 Obsidian 需要付费其实本地个人使用并不需要。关于这一点后面还会专门展开。2. Vault 的目录结构.obsidian 文件夹里到底有什么既然 Vault 是文件夹那就应该用分析文件夹的眼光去看待它。默认情况下一个新建 Vault 里的内容非常少你的笔记文件、你手动创建的附件文件夹以及 Obsidian 自动生成的.obsidian隐藏目录。先看整体结构。在终端里执行tree -a ~/Documents/MyNotes输出大概是这样目录名称只是示例my-notes/ ├── .obsidian/ │ ├── app.json │ ├── appearance.json │ ├── core-plugins.json │ ├── community-plugins.json │ ├── workspace.json │ └── ... ├── 001 项目/ │ └── 产品调研.md ├── assets/ │ └── 架构图.png ├── 每日笔记/ │ ├── 2025-06-01.md │ └── 2025-06-02.md └── 首页.md如果没有安装 tree 命令也可以用 find 代替find ~/Documents/MyNotes -maxdepth 2 | head -502.1 .obsidian 是 Vault 的“配置中心”.obsidian目录里保存的是这个 Vault 的本地设置包括主题、启用的插件、工作区布局、快捷键等。换句话说Obsidian 的配置不是全局统一存放在安装目录里的而是跟随 Vault 文件夹走的。这就是为什么“复制 Vault 文件夹就等于复制了一份完整笔记环境和配置”。正因为如此把整个 Vault 打包备份后换一台电脑打开界面和插件基本能恢复原样。不过要注意.obsidian里的 JSON 文件字段会随版本变化官方并不建议手动修改除非你清楚自己在做什么。如果.obsidian被误删会发生什么答案是笔记文件一个都不会少只是 Obsidian 会重新生成一份默认配置之前设置的主题、插件列表都会丢失。所以.obsidian虽然是个隐藏目录但它是值得纳入备份的重要部分。2.2 笔记文件与附件的组织方式Obsidian 默认把新建笔记放在 Vault 根目录如果你一直不整理时间一长根目录会堆满文件。比较常见的做法是建几个一级目录比如“每日笔记”“项目”“主题”“资源”等按自己的习惯分门别类。图片、PDF 等附件建议统一放到一个独立目录里比如assets或attachments。这样在备份、迁移、切换到 Git 管理时都会省去很多麻烦。Obsidian 在设置里也提供了“新附件默认存放位置”的选项新手可以在一开始就把附件目录配置好避免图片散落各处。2.3 数据格式Markdown 与 YAML FrontmatterVault 里的笔记主体是 Markdown 文本但很多高阶插件会读取笔记开头的 YAML Frontmatter 区域。所谓 Frontmatter就是用两行---包裹起来的一组键值对写在文件最顶部比如--- title: 示例笔记 tags: - 读书 - 方法论 created: 2025-06-01 --- # 示例笔记 正文内容用 Markdown 书写。这段内容依然是一个纯文本文件没有任何特殊二进制结构。Dataview 等插件之所以能做“把笔记当数据库查询”的操作靠的就是读取 YAML 字段和正文文本。可见 Vault 的开放性是从底层文件格式就确立的。3. Obsidian 安装与第一个 Vault 创建3.1 下载与安装Obsidian 官方支持 Windows、macOS、Linux、iOS、Android。桌面端从官网下载安装包移动端从官方应用商店下载即可。具体版本以官网发布为准不建议在第三方网站下载不明安装包。有一个高频热搜词是“obsidian 下载太慢了”。这通常不是软件本身的问题而是官方服务器在部分网络环境下响应较慢。稳妥的做法是错峰下载、检查当前网络环境或从官方应用商店获取移动端安装包。这里不展开讨论任何第三方加速工具安全第一。安装完成后打开 Obsidian会看到两个关键选项Create new vault 和 Open folder as vault。前者创建全新 Vault后者把已有文件夹当作 Vault 打开。3.2 创建 Vault 的两种方式方式一新建 Vault。点击 Create new vault输入 Vault 名称和存放路径Obsidian 会创建对应文件夹并初始化配置。方式二打开已有文件夹。如果你之前用 Typora、VS Code 或者其他 Markdown 工具维护过一个笔记目录直接选择 Open folder as vault就能把那个目录升级成 Obsidian 的 Vault。这种方式非常适合从其他 Markdown 工作流迁移过来的用户。这里给出一个命令行创建最小 Vault 的示例mkdir -p ~/Documents/MyNotes/assets cd ~/Documents/MyNotes echo # 我的第一则笔记 今天是开始使用 Obsidian 的第一天。 第一则笔记.md然后打开 Obsidian点击 Open folder as vault选择~/Documents/MyNotes。Obsidian 会扫描目录自动发现第一则笔记.md这个文件夹就正式成为一个可用的 Vault。3.3 验证第一个 Vault 是否创建成功判断 Vault 是否创建成功有三个信号第一Obsidian 左侧文件列表里能看到第一则笔记.md。第二打开文件后能正常编辑和保存 Markdown。第三回到文件管理器确认~/Documents/MyNotes目录下出现了.obsidian隐藏文件夹。如果打开后什么都没看到大概率是选错了文件夹路径。关闭当前 Vault重新用 Open folder as vault 选择正确目录即可。3.4 一个非常常见的坑在系统文件管理器里重命名笔记Vault 是文件夹不代表你应该用文件管理器去随意重命名笔记。Obsidian 的链接本质上是对“文件名”的引用。当你在 Obsidian 里右键重命名笔记时它会自动把所有引用这篇笔记的双链同步更新但在系统文件管理器里直接改名Obsidian 并不会知道新旧名称之间的对应关系于是图谱里可能出现断链之前引用它的笔记也无法再跳转。正确做法是尽量在 Obsidian 内完成重命名操作。如果已经在系统里改名了就需要手动找到所有写作[[旧名称]]的地方改成新名称。这个坑几乎每个新手都会踩提前知道能省下不少修复链接的时间。4. 从文件夹视角理解双链、标签、图谱4.1 双链的本质是“文件名引用”Obsidian 最具标志性的双链在文件夹视角下并不神秘。当你在笔记 A 里写[[笔记B]]Obsidian 要做的事情就是在当前 Vault 文件夹里找名为笔记B.md的文件并把这段引用变成可点击跳转的链接。这意味着同一 Vault 里最好不要出现两个同名笔记。如果存在两个同名笔记Obsidian 在解析双链时就会遇到歧义[[笔记B]]到底指向哪个文件虽然 Obsidian 会给出选择但这会极大降低知识库的稳定性。4.2 标签与搜索的底层逻辑标签在 Obsidian 里看起来是一个独立功能其实底层依然是对文本的扫描。你在正文里写#读书Obsidian 就会扫描所有.md文件把这个标签统计进标签面板。YAML Frontmatter 里的tags字段也同样参与索引。所以说标签不是额外数据库里的字段而是 Vault 内文本内容的一种约定。当你用“标签”组织笔记时本质上还是在处理文本。这也是为什么外部脚本可以轻松统计标签因为这部分数据就在文件里躺着。4.3 图谱视图显示的是文件间引用网络很多人第一次看到 Obsidian 的 Graph View 图谱时会觉得非常震撼仿佛软件构建出了一个“知识网络”。但从技术角度看图谱只是把“哪些文件被哪些文件引用”这件事可视化了出来。节点是文件连线是双链或标签关系。因此图谱不会自动反映文件夹的层级结构。你精心设计的目录树不会直接变成图谱里的连线只有通过双链、标签和搜索索引文件之间的关系才会浮现。理解这一点就能解释“为什么我的图谱很乱”和“为什么我建了文件夹但图谱里没有反应”这类常见困惑。4.4 插件生态建立在这个文件夹解析之上Obsidian 的插件社区之所以丰富根本原因还是 Vault 足够开放。Dataview 在扫描 YAML 和正文后生成列表Git 插件对文件夹做版本管理Excalidraw 在 Vault 里保存绘图文件Web Clipper 把网页剪藏成 Markdown 存入 VaultGraph Analysis 则提供更多图谱维度的分析。更进一步由于 Vault 是开放文件夹外部 AI 工具、命令行脚本、个人知识库项目也能直接读取和索引这些 Markdown 文件。这也解释了为什么像 Codex 与 Obsidian 结合、LLM Wiki 搭建个人知识库这类话题会越来越热。数据没有被锁在某个软件格式里谁都能用这才有大量第三方工具存在的空间。5. 用命令行与脚本管理 Vault因为 Vault 是文件夹所以用终端和脚本管理笔记是顺理成章的事。这一节会给出几个可运行的最小示例帮你更直观地感受到 Vault 的开放性。5.1 查看 Vault 整体结构使用 tree 命令可以快速查看 Vault 目录树包括隐藏的.obsidian目录tree -a ~/Documents/MyNotes如果你的环境没有 tree也可以用 findfind ~/Documents/MyNotes -maxdepth 2 | head -50这两种方式都能让你在终端里快速确认 Vault 里到底有什么文件哪些目录占用了空间附件是不是乱放。5.2 快速统计笔记数量和文字量find ~/Documents/MyNotes -name *.md | wc -l这条命令统计 Vault 里有多少篇 Markdown 笔记。find ~/Documents/MyNotes -name *.md -exec cat {} | wc -m这条命令统计所有 Markdown 文件的总字符数可以大致评估知识库的规模。如果统计结果明显偏离预期说明有些文件没有用.md后缀或者 Vault 里混入了大量非笔记文件。5.3 用 Python 做一个标签统计脚本下面这段 Python 脚本会扫描 Vault 下的所有.md文件用正则提取正文中的#标签并统计每个标签出现的次数。这是一个很好的手写示例用来验证外部程序读写 Vault 的能力。# count_tags.py import re from pathlib import Path vault_path Path.home() / Documents / MyNotes tag_counter {} for md_file in vault_path.rglob(*.md): text md_file.read_text(encodingutf-8, errorsignore) # 匹配正文中的 #标签 tags re.findall(r#([\u4e00-\u9fa5\w/-]), text) for tag in tags: # 只统计标签第一级也可以根据需求调整 top_tag tag.split(/)[0] tag_counter[top_tag] tag_counter.get(top_tag, 0) 1 for tag, count in sorted(tag_counter.items(), keylambda x: x[1], reverseTrue): print(f{tag}: {count})这里要说明脚本是一个简化版本它只匹配正文中的#标签没有处理 YAML Frontmatter 里的tags列表也没有过滤标题行中的井号。如果发现统计结果和 Obsidian 标签面板对不上可以先从这两个差异入手检查。5.4 运行与验证在 Vault 所在目录的同级位置运行python3 count_tags.py预期输出是类似这样的排序结果读书: 12 项目: 8 方法论: 5如果命令不报错并且数字与 Obsidian 标签面板中的主流标签大致吻合就说明外部脚本已经成功读取了 Vault 内部数据。这个示例的意义在于你已经可以把 Vault 当作普通文本数据集来处理后续想按标签归档、生成周报、做全文检索都可以在此基础上扩展。6. 多设备同步与云端存储方案怎么选不少用户问“Obsidian 云端存储选哪家”这个问题背后藏着一个更核心的问题多个设备之间怎么让同一个 Vault 保持同步。既然 Vault 是文件夹答案就很清晰——你只需要解决“让一个文件夹在多个设备间保持一致”的问题。6.1 官方 Sync 方案Obsidian 官方提供了名为 Sync 的付费同步服务特点是端到端加密、按 Vault 同步、移动端体验顺滑冲突处理也比较自动化。Publish 则是把笔记发布成网站的付费服务。官方把同步和发布做成收费项而本地软件本身免费这是 Obsidian 一直以来的商业模式。官方 Sync 适合以下用户不熟悉技术方案、需要手机和电脑无缝切换、愿意为省心付费并且重视笔记数据加密。需要提醒的是很多新用户会因为“Obsidian 收费”这个疑惑而犹豫要不要入坑。实际体验下来如果你只在单台电脑上使用或者愿意自己用同步盘/Git 解决多设备问题本地核心功能完全够用不需要订阅官方服务。6.2 自选文件夹同步方案如果你不想订阅官方 Sync可以用任何“文件夹级同步”的方案。常见的包括系统同步盘比如 iCloud、OneDrive、坚果云等把 Vault 文件夹放进同步盘由同步盘负责多设备同步。WebDAV部分网盘提供 WebDAV 接口可以通过第三方工具接入移动端。Git 仓库适合开发者把 Vault 做成 Git 仓库通过远程仓库同步借助 Git 做版本回溯。自建同步服务如果你有服务器或 NAS也可以自行搭建同步方案本质同样是同步一个文件夹。不管你选哪种方案都有一个判断标准同步方案必须能同步.obsidian隐藏文件夹否则换电脑后插件和主题设置会丢失。有些同步工具默认不同步隐藏文件需要手动开启这是一个容易忽略的细节。6.3 冲突文件与处理方式多设备同步最大的风险是同一篇笔记在多个设备上被同时修改。同步盘遇到这种情况时通常会在文件名中加入“冲突”或“conflicted”之类的标记生成一个冲突副本。Obsidian 里也一样你会在文件列表中看到类似笔记A (conflicted 2025-06-01).md的文件。处理冲突的正确步骤是打开原文件和冲突副本人工对比内容保留需要的那一份把多余的冲突副本删除。不要直接把冲突文件全部删掉否则可能丢掉某些设备上新增的内容。想减少冲突比较实用的习惯是一个时间段内只在主要设备上编辑、移动端只做快速捕捉、回到电脑后再整理。Obsidian 并不是在线协作文档工具它更适合“单人多设备”的本地优先工作流。6.4 手机端 Obsidian 的注意点手机端 Obsidian 打开 Vault 时本质也是打开一个本地文件夹。首次使用需要先把同步盘里的 Vault 下载到手机或者通过支持 WebDAV 的 App 拉取文件。手机端适合临时查看和快速记录不适合大量移动笔记文件。如果你希望在手机和电脑之间高频编辑需要先确认同步方案是否可靠。插件更新在手机端需要网络如果下载缓慢检查网络环境后重试插件列表本身记录在.obsidian/community-plugins.json中。7. Vault 常见问题与排查思路新手在使用 Vault 时问题往往集中在“找不到笔记”“链接失效”“配置丢失”“同步冲突”这几类。这里整理了一张常见问题表方便你按图索骥。问题现象可能原因排查方式解决方案打开 Obsidian 后看不到原有笔记打开的 Vault 路径不对或文件夹被移动查看左侧文件列表和最近打开记录使用 Open folder as vault 重新选择文件夹在系统文件管理器中重命名笔记双链失效双链基于文件名引用在图谱视图查看断链在 Obsidian 内重命名或手动更新引用.obsidian 被误删手动清理时删掉隐藏目录检查目录是否重新生成重新配置之后将 .obsidian 纳入备份多设备同步后出现冲突副本同一笔记在不同设备同时被修改搜索 conflicted 或 冲突 文件保留有效版本删除多余冲突副本图片无法显示附件路径改变或附件未同步对比笔记中的图片引用和实际文件位置统一附件目录更新引用路径插件市场打不开或下载慢网络环境问题检查网络后重试错峰重试或手动下载插件到 .obsidian/plugins手机端插件无法更新网络或插件权限问题检查手机端设置中的插件列表和网络连接确认网络正常必要时重新安装插件还有两个经常被搜索的问题值得单独说明。第一Obsidian 支持多级索引吗它当然支持多级文件夹目录层数没有硬性限制。但 Obsidian 本身并没有传统笔记软件那种强制的“笔记本-分区-页面”三层结构你既可以靠文件夹层级来组织也可以靠标签、双链和 MOC 索引笔记来实现更灵活的导航。第二如何打印或导出笔记Obsidian 内置支持将笔记导出为 PDF也可以使用系统打印预览功能进行打印。如果你经常需要输出文档建议在写笔记时注意 Markdown 标题层级导出效果会更规整。8. 把 Vault 当文件夹管理的工程最佳实践8.1 文件夹结构与命名不要一开始就设计十几层嵌套目录那样会带来维护成本。更推荐一种轻量结构收件箱、项目、主题、资源、模板、每日笔记。收件箱用来临时记录想法定期整理进项目或主题模板目录保存常用模板每日笔记用于时间线记录。文件名规范同样重要。尽量不重名、不包含影响跨平台的特殊字符。中文文件名在 Obsidian 中完全可行但如果你想用脚本批量处理需要注意路径编码问题。用 Markdown 标题作为笔记主标题文件名短小精悍即可。8.2 配置文件的备份策略.obsidian目录里保存着 Vault 的设置、主题和插件列表建议纳入备份或同步。如果你使用 Git可以在仓库里保留core-plugins.json和community-plugins.json但workspace.json会随打开关闭频繁变动容易产生大量无关提交。个人项目可以不 care团队项目则可以在.gitignore里忽略它或者接受这种频繁变更。8.3 附件与图片管理在 Obsidian 设置里提前指定附件默认目录比如assets可以避免图片和笔记混在一起。大体积二进制文件比如视频、压缩包、设计稿源文件不建议直接放进 Vault它会拖慢同步和索引速度。如果一定要保存可以放到 Vault 外部的独立目录在笔记里记录路径或链接。8.4 安全与隐私Vault 是明文文件因此不要在笔记里明文写重要密码、密钥、身份证号等敏感信息。如果确实需要在本地保存敏感内容应使用系统磁盘加密、密码管理器或专业加密工具。同时注意同步盘的账号安全因为同步盘的权限通常意味着所有笔记内容的权限。当你想把 Vault 接入 AI 工具时也一定要先确认工具是否有权读取这个文件夹。不要让来路不明的脚本或在线服务扫描私密 Vault这是最小权限原则在笔记场景中的体现。8.5 关于“Obsidian 收费”的最终澄清经常看到有人问“Obsidian 收费吗”。准确说法是本地软件免费官方同步服务 Sync 和发布服务 Publish Obsidian入门：Vault本质是文件夹，一文搞懂核心概念
你下载好 Obsidian第一次打开软件迎面就是一个英文弹窗Create new vault。很多新手在这里就卡住了。vault 这个词一看就不是普通单词搜索引擎里伴随它出现的往往还有“知识库搭建”“个人信息管理系统”这类让人紧张的说法于是你会误以为要用 Obsidian得先学会一套高深的知识管理哲学。但我要先给出一个判断Vault 在物理世界里就是一个普普通通的文件夹。没有数据库、没有私有格式、没有云端绑定。Obsidian 所做的全部事情就是把这个文件夹里的 Markdown 文件读进来再用双链、标签、图谱这些能力让文件夹“活”起来。理解这一点比记住一百个快捷键都重要也是整个 Obsidian 入门过程中最值得先想明白的事。这篇文章不会讲高深方法论而是从一个最容易被忽略的事实切入Vault 就是文件夹。我会带你从文件管理器视角看 Vault 的目录结构给出创建 Vault 的具体步骤讲解.obsidian隐藏目录、双链和图谱的底层逻辑并讨论多设备同步、常见误区、最佳实践。如果你正被“创建 Vault”这一步卡住或者用 Obsidian 一段时间后总觉得概念很虚这篇文章会帮你把地基打牢。另外说明一个背景Obsidian 社区里大量进阶技巧比如 Dataview、Git、图谱分析、接入 AI 等本质上都在操作文件夹里的纯文本文件。只要你理解了 Vault 的文件夹本质后面学任何插件都会快很多。1. Vault 不是“知识库管理系统”而是一个文件夹1.1 先在文件管理器里证明这件事你可以直接在系统里新建一个文件夹命名为 MyNotes。Windows 用资源管理器macOS 用 FinderLinux 用户用你喜欢的任何文件管理器都可以。然后打开 Obsidian点击界面上的 “Open folder as vault”选中刚才新建的文件夹。Obsidian 会立即进入一个新工作区。此时你回到文件管理器刷新一下会发现 MyNotes 里多了一个名为.obsidian的隐藏文件夹仅此而已。没有自动创建什么数据库文件没有上传你的任何内容到云端也没有强制你选择“笔记格式”。一句话概括Obsidian 打开了一个文件夹并在这个文件夹里放了一些配置文件。如果你习惯用命令行可以先用如下命令创建这个最小 Vaultmkdir -p ~/Documents/MyNotes然后打开 Obsidian通过 “Open folder as vault” 选择~/Documents/MyNotes即可。这个文件夹从这一刻起就成了 Obsidian 语境里的 Vault。1.2 为什么这个设计值得被认真对待传统笔记软件通常把内容存进自己的数据库或云服务器。看起来用户是在写笔记实际上数据被封装在一个“黑盒”里你只能通过软件本身读写迁移时需要专门的导出功能如果软件停止服务数据能不能完整拿回来也是个未知数。Obsidian 走的是完全不同的路线。Vault 里的每一篇笔记都是一个.md文件也就是纯文本 Markdown。你甚至不用 Obsidian 来打开它用 Typora、VS Code、记事本任意一个支持文本编辑的工具都能直接读取和修改。从文件系统的视角看Vault 就是一个普通目录可以被复制、压缩、移动到任何地方。这个设计带来的直接收益有三个第一数据所有权明确。你不需要担心某个云服务关闭后笔记丢失只要文件夹在笔记就在。第二迁移成本几乎为零。想从 Obsidian 换到其他 Markdown 工具直接把文件夹交给新工具就行不需要导入导出。第三外部工具可以参与管理。Git、同步盘、自动化脚本、AI 工具都能直接面向文件夹里的纯文本文件工作不会受制于私有格式。1.3 传统笔记软件与 Obsidian Vault 的对比为了更直观这里用一个表格对比传统笔记应用和 Obsidian Vault对比维度传统笔记应用Obsidian Vault数据存储位置云端或私有数据库本地文件夹文件格式私有格式需要导出转换纯文本 Markdown是否依赖网络多数强依赖本地优先可选同步数据迁移需要导出导入流程直接复制文件夹扩展性受平台限制插件与外部脚本均可操作成本模型通常订阅制本地使用免费Sync/Publish 收费表格里的“本地使用免费”特别值得强调。Obsidian 官方收费的是同步服务 Sync 和发布服务 Publish而不是笔记软件本身。很多新手误以为 Obsidian 需要付费其实本地个人使用并不需要。关于这一点后面还会专门展开。2. Vault 的目录结构.obsidian 文件夹里到底有什么既然 Vault 是文件夹那就应该用分析文件夹的眼光去看待它。默认情况下一个新建 Vault 里的内容非常少你的笔记文件、你手动创建的附件文件夹以及 Obsidian 自动生成的.obsidian隐藏目录。先看整体结构。在终端里执行tree -a ~/Documents/MyNotes输出大概是这样目录名称只是示例my-notes/ ├── .obsidian/ │ ├── app.json │ ├── appearance.json │ ├── core-plugins.json │ ├── community-plugins.json │ ├── workspace.json │ └── ... ├── 001 项目/ │ └── 产品调研.md ├── assets/ │ └── 架构图.png ├── 每日笔记/ │ ├── 2025-06-01.md │ └── 2025-06-02.md └── 首页.md如果没有安装 tree 命令也可以用 find 代替find ~/Documents/MyNotes -maxdepth 2 | head -502.1 .obsidian 是 Vault 的“配置中心”.obsidian目录里保存的是这个 Vault 的本地设置包括主题、启用的插件、工作区布局、快捷键等。换句话说Obsidian 的配置不是全局统一存放在安装目录里的而是跟随 Vault 文件夹走的。这就是为什么“复制 Vault 文件夹就等于复制了一份完整笔记环境和配置”。正因为如此把整个 Vault 打包备份后换一台电脑打开界面和插件基本能恢复原样。不过要注意.obsidian里的 JSON 文件字段会随版本变化官方并不建议手动修改除非你清楚自己在做什么。如果.obsidian被误删会发生什么答案是笔记文件一个都不会少只是 Obsidian 会重新生成一份默认配置之前设置的主题、插件列表都会丢失。所以.obsidian虽然是个隐藏目录但它是值得纳入备份的重要部分。2.2 笔记文件与附件的组织方式Obsidian 默认把新建笔记放在 Vault 根目录如果你一直不整理时间一长根目录会堆满文件。比较常见的做法是建几个一级目录比如“每日笔记”“项目”“主题”“资源”等按自己的习惯分门别类。图片、PDF 等附件建议统一放到一个独立目录里比如assets或attachments。这样在备份、迁移、切换到 Git 管理时都会省去很多麻烦。Obsidian 在设置里也提供了“新附件默认存放位置”的选项新手可以在一开始就把附件目录配置好避免图片散落各处。2.3 数据格式Markdown 与 YAML FrontmatterVault 里的笔记主体是 Markdown 文本但很多高阶插件会读取笔记开头的 YAML Frontmatter 区域。所谓 Frontmatter就是用两行---包裹起来的一组键值对写在文件最顶部比如--- title: 示例笔记 tags: - 读书 - 方法论 created: 2025-06-01 --- # 示例笔记 正文内容用 Markdown 书写。这段内容依然是一个纯文本文件没有任何特殊二进制结构。Dataview 等插件之所以能做“把笔记当数据库查询”的操作靠的就是读取 YAML 字段和正文文本。可见 Vault 的开放性是从底层文件格式就确立的。3. Obsidian 安装与第一个 Vault 创建3.1 下载与安装Obsidian 官方支持 Windows、macOS、Linux、iOS、Android。桌面端从官网下载安装包移动端从官方应用商店下载即可。具体版本以官网发布为准不建议在第三方网站下载不明安装包。有一个高频热搜词是“obsidian 下载太慢了”。这通常不是软件本身的问题而是官方服务器在部分网络环境下响应较慢。稳妥的做法是错峰下载、检查当前网络环境或从官方应用商店获取移动端安装包。这里不展开讨论任何第三方加速工具安全第一。安装完成后打开 Obsidian会看到两个关键选项Create new vault 和 Open folder as vault。前者创建全新 Vault后者把已有文件夹当作 Vault 打开。3.2 创建 Vault 的两种方式方式一新建 Vault。点击 Create new vault输入 Vault 名称和存放路径Obsidian 会创建对应文件夹并初始化配置。方式二打开已有文件夹。如果你之前用 Typora、VS Code 或者其他 Markdown 工具维护过一个笔记目录直接选择 Open folder as vault就能把那个目录升级成 Obsidian 的 Vault。这种方式非常适合从其他 Markdown 工作流迁移过来的用户。这里给出一个命令行创建最小 Vault 的示例mkdir -p ~/Documents/MyNotes/assets cd ~/Documents/MyNotes echo # 我的第一则笔记 今天是开始使用 Obsidian 的第一天。 第一则笔记.md然后打开 Obsidian点击 Open folder as vault选择~/Documents/MyNotes。Obsidian 会扫描目录自动发现第一则笔记.md这个文件夹就正式成为一个可用的 Vault。3.3 验证第一个 Vault 是否创建成功判断 Vault 是否创建成功有三个信号第一Obsidian 左侧文件列表里能看到第一则笔记.md。第二打开文件后能正常编辑和保存 Markdown。第三回到文件管理器确认~/Documents/MyNotes目录下出现了.obsidian隐藏文件夹。如果打开后什么都没看到大概率是选错了文件夹路径。关闭当前 Vault重新用 Open folder as vault 选择正确目录即可。3.4 一个非常常见的坑在系统文件管理器里重命名笔记Vault 是文件夹不代表你应该用文件管理器去随意重命名笔记。Obsidian 的链接本质上是对“文件名”的引用。当你在 Obsidian 里右键重命名笔记时它会自动把所有引用这篇笔记的双链同步更新但在系统文件管理器里直接改名Obsidian 并不会知道新旧名称之间的对应关系于是图谱里可能出现断链之前引用它的笔记也无法再跳转。正确做法是尽量在 Obsidian 内完成重命名操作。如果已经在系统里改名了就需要手动找到所有写作[[旧名称]]的地方改成新名称。这个坑几乎每个新手都会踩提前知道能省下不少修复链接的时间。4. 从文件夹视角理解双链、标签、图谱4.1 双链的本质是“文件名引用”Obsidian 最具标志性的双链在文件夹视角下并不神秘。当你在笔记 A 里写[[笔记B]]Obsidian 要做的事情就是在当前 Vault 文件夹里找名为笔记B.md的文件并把这段引用变成可点击跳转的链接。这意味着同一 Vault 里最好不要出现两个同名笔记。如果存在两个同名笔记Obsidian 在解析双链时就会遇到歧义[[笔记B]]到底指向哪个文件虽然 Obsidian 会给出选择但这会极大降低知识库的稳定性。4.2 标签与搜索的底层逻辑标签在 Obsidian 里看起来是一个独立功能其实底层依然是对文本的扫描。你在正文里写#读书Obsidian 就会扫描所有.md文件把这个标签统计进标签面板。YAML Frontmatter 里的tags字段也同样参与索引。所以说标签不是额外数据库里的字段而是 Vault 内文本内容的一种约定。当你用“标签”组织笔记时本质上还是在处理文本。这也是为什么外部脚本可以轻松统计标签因为这部分数据就在文件里躺着。4.3 图谱视图显示的是文件间引用网络很多人第一次看到 Obsidian 的 Graph View 图谱时会觉得非常震撼仿佛软件构建出了一个“知识网络”。但从技术角度看图谱只是把“哪些文件被哪些文件引用”这件事可视化了出来。节点是文件连线是双链或标签关系。因此图谱不会自动反映文件夹的层级结构。你精心设计的目录树不会直接变成图谱里的连线只有通过双链、标签和搜索索引文件之间的关系才会浮现。理解这一点就能解释“为什么我的图谱很乱”和“为什么我建了文件夹但图谱里没有反应”这类常见困惑。4.4 插件生态建立在这个文件夹解析之上Obsidian 的插件社区之所以丰富根本原因还是 Vault 足够开放。Dataview 在扫描 YAML 和正文后生成列表Git 插件对文件夹做版本管理Excalidraw 在 Vault 里保存绘图文件Web Clipper 把网页剪藏成 Markdown 存入 VaultGraph Analysis 则提供更多图谱维度的分析。更进一步由于 Vault 是开放文件夹外部 AI 工具、命令行脚本、个人知识库项目也能直接读取和索引这些 Markdown 文件。这也解释了为什么像 Codex 与 Obsidian 结合、LLM Wiki 搭建个人知识库这类话题会越来越热。数据没有被锁在某个软件格式里谁都能用这才有大量第三方工具存在的空间。5. 用命令行与脚本管理 Vault因为 Vault 是文件夹所以用终端和脚本管理笔记是顺理成章的事。这一节会给出几个可运行的最小示例帮你更直观地感受到 Vault 的开放性。5.1 查看 Vault 整体结构使用 tree 命令可以快速查看 Vault 目录树包括隐藏的.obsidian目录tree -a ~/Documents/MyNotes如果你的环境没有 tree也可以用 findfind ~/Documents/MyNotes -maxdepth 2 | head -50这两种方式都能让你在终端里快速确认 Vault 里到底有什么文件哪些目录占用了空间附件是不是乱放。5.2 快速统计笔记数量和文字量find ~/Documents/MyNotes -name *.md | wc -l这条命令统计 Vault 里有多少篇 Markdown 笔记。find ~/Documents/MyNotes -name *.md -exec cat {} | wc -m这条命令统计所有 Markdown 文件的总字符数可以大致评估知识库的规模。如果统计结果明显偏离预期说明有些文件没有用.md后缀或者 Vault 里混入了大量非笔记文件。5.3 用 Python 做一个标签统计脚本下面这段 Python 脚本会扫描 Vault 下的所有.md文件用正则提取正文中的#标签并统计每个标签出现的次数。这是一个很好的手写示例用来验证外部程序读写 Vault 的能力。# count_tags.py import re from pathlib import Path vault_path Path.home() / Documents / MyNotes tag_counter {} for md_file in vault_path.rglob(*.md): text md_file.read_text(encodingutf-8, errorsignore) # 匹配正文中的 #标签 tags re.findall(r#([\u4e00-\u9fa5\w/-]), text) for tag in tags: # 只统计标签第一级也可以根据需求调整 top_tag tag.split(/)[0] tag_counter[top_tag] tag_counter.get(top_tag, 0) 1 for tag, count in sorted(tag_counter.items(), keylambda x: x[1], reverseTrue): print(f{tag}: {count})这里要说明脚本是一个简化版本它只匹配正文中的#标签没有处理 YAML Frontmatter 里的tags列表也没有过滤标题行中的井号。如果发现统计结果和 Obsidian 标签面板对不上可以先从这两个差异入手检查。5.4 运行与验证在 Vault 所在目录的同级位置运行python3 count_tags.py预期输出是类似这样的排序结果读书: 12 项目: 8 方法论: 5如果命令不报错并且数字与 Obsidian 标签面板中的主流标签大致吻合就说明外部脚本已经成功读取了 Vault 内部数据。这个示例的意义在于你已经可以把 Vault 当作普通文本数据集来处理后续想按标签归档、生成周报、做全文检索都可以在此基础上扩展。6. 多设备同步与云端存储方案怎么选不少用户问“Obsidian 云端存储选哪家”这个问题背后藏着一个更核心的问题多个设备之间怎么让同一个 Vault 保持同步。既然 Vault 是文件夹答案就很清晰——你只需要解决“让一个文件夹在多个设备间保持一致”的问题。6.1 官方 Sync 方案Obsidian 官方提供了名为 Sync 的付费同步服务特点是端到端加密、按 Vault 同步、移动端体验顺滑冲突处理也比较自动化。Publish 则是把笔记发布成网站的付费服务。官方把同步和发布做成收费项而本地软件本身免费这是 Obsidian 一直以来的商业模式。官方 Sync 适合以下用户不熟悉技术方案、需要手机和电脑无缝切换、愿意为省心付费并且重视笔记数据加密。需要提醒的是很多新用户会因为“Obsidian 收费”这个疑惑而犹豫要不要入坑。实际体验下来如果你只在单台电脑上使用或者愿意自己用同步盘/Git 解决多设备问题本地核心功能完全够用不需要订阅官方服务。6.2 自选文件夹同步方案如果你不想订阅官方 Sync可以用任何“文件夹级同步”的方案。常见的包括系统同步盘比如 iCloud、OneDrive、坚果云等把 Vault 文件夹放进同步盘由同步盘负责多设备同步。WebDAV部分网盘提供 WebDAV 接口可以通过第三方工具接入移动端。Git 仓库适合开发者把 Vault 做成 Git 仓库通过远程仓库同步借助 Git 做版本回溯。自建同步服务如果你有服务器或 NAS也可以自行搭建同步方案本质同样是同步一个文件夹。不管你选哪种方案都有一个判断标准同步方案必须能同步.obsidian隐藏文件夹否则换电脑后插件和主题设置会丢失。有些同步工具默认不同步隐藏文件需要手动开启这是一个容易忽略的细节。6.3 冲突文件与处理方式多设备同步最大的风险是同一篇笔记在多个设备上被同时修改。同步盘遇到这种情况时通常会在文件名中加入“冲突”或“conflicted”之类的标记生成一个冲突副本。Obsidian 里也一样你会在文件列表中看到类似笔记A (conflicted 2025-06-01).md的文件。处理冲突的正确步骤是打开原文件和冲突副本人工对比内容保留需要的那一份把多余的冲突副本删除。不要直接把冲突文件全部删掉否则可能丢掉某些设备上新增的内容。想减少冲突比较实用的习惯是一个时间段内只在主要设备上编辑、移动端只做快速捕捉、回到电脑后再整理。Obsidian 并不是在线协作文档工具它更适合“单人多设备”的本地优先工作流。6.4 手机端 Obsidian 的注意点手机端 Obsidian 打开 Vault 时本质也是打开一个本地文件夹。首次使用需要先把同步盘里的 Vault 下载到手机或者通过支持 WebDAV 的 App 拉取文件。手机端适合临时查看和快速记录不适合大量移动笔记文件。如果你希望在手机和电脑之间高频编辑需要先确认同步方案是否可靠。插件更新在手机端需要网络如果下载缓慢检查网络环境后重试插件列表本身记录在.obsidian/community-plugins.json中。7. Vault 常见问题与排查思路新手在使用 Vault 时问题往往集中在“找不到笔记”“链接失效”“配置丢失”“同步冲突”这几类。这里整理了一张常见问题表方便你按图索骥。问题现象可能原因排查方式解决方案打开 Obsidian 后看不到原有笔记打开的 Vault 路径不对或文件夹被移动查看左侧文件列表和最近打开记录使用 Open folder as vault 重新选择文件夹在系统文件管理器中重命名笔记双链失效双链基于文件名引用在图谱视图查看断链在 Obsidian 内重命名或手动更新引用.obsidian 被误删手动清理时删掉隐藏目录检查目录是否重新生成重新配置之后将 .obsidian 纳入备份多设备同步后出现冲突副本同一笔记在不同设备同时被修改搜索 conflicted 或 冲突 文件保留有效版本删除多余冲突副本图片无法显示附件路径改变或附件未同步对比笔记中的图片引用和实际文件位置统一附件目录更新引用路径插件市场打不开或下载慢网络环境问题检查网络后重试错峰重试或手动下载插件到 .obsidian/plugins手机端插件无法更新网络或插件权限问题检查手机端设置中的插件列表和网络连接确认网络正常必要时重新安装插件还有两个经常被搜索的问题值得单独说明。第一Obsidian 支持多级索引吗它当然支持多级文件夹目录层数没有硬性限制。但 Obsidian 本身并没有传统笔记软件那种强制的“笔记本-分区-页面”三层结构你既可以靠文件夹层级来组织也可以靠标签、双链和 MOC 索引笔记来实现更灵活的导航。第二如何打印或导出笔记Obsidian 内置支持将笔记导出为 PDF也可以使用系统打印预览功能进行打印。如果你经常需要输出文档建议在写笔记时注意 Markdown 标题层级导出效果会更规整。8. 把 Vault 当文件夹管理的工程最佳实践8.1 文件夹结构与命名不要一开始就设计十几层嵌套目录那样会带来维护成本。更推荐一种轻量结构收件箱、项目、主题、资源、模板、每日笔记。收件箱用来临时记录想法定期整理进项目或主题模板目录保存常用模板每日笔记用于时间线记录。文件名规范同样重要。尽量不重名、不包含影响跨平台的特殊字符。中文文件名在 Obsidian 中完全可行但如果你想用脚本批量处理需要注意路径编码问题。用 Markdown 标题作为笔记主标题文件名短小精悍即可。8.2 配置文件的备份策略.obsidian目录里保存着 Vault 的设置、主题和插件列表建议纳入备份或同步。如果你使用 Git可以在仓库里保留core-plugins.json和community-plugins.json但workspace.json会随打开关闭频繁变动容易产生大量无关提交。个人项目可以不 care团队项目则可以在.gitignore里忽略它或者接受这种频繁变更。8.3 附件与图片管理在 Obsidian 设置里提前指定附件默认目录比如assets可以避免图片和笔记混在一起。大体积二进制文件比如视频、压缩包、设计稿源文件不建议直接放进 Vault它会拖慢同步和索引速度。如果一定要保存可以放到 Vault 外部的独立目录在笔记里记录路径或链接。8.4 安全与隐私Vault 是明文文件因此不要在笔记里明文写重要密码、密钥、身份证号等敏感信息。如果确实需要在本地保存敏感内容应使用系统磁盘加密、密码管理器或专业加密工具。同时注意同步盘的账号安全因为同步盘的权限通常意味着所有笔记内容的权限。当你想把 Vault 接入 AI 工具时也一定要先确认工具是否有权读取这个文件夹。不要让来路不明的脚本或在线服务扫描私密 Vault这是最小权限原则在笔记场景中的体现。8.5 关于“Obsidian 收费”的最终澄清经常看到有人问“Obsidian 收费吗”。准确说法是本地软件免费官方同步服务 Sync 和发布服务 Publish