--- tags: - yaml aliases: - yaml用法 笔记类型: 永久笔记 日期: 2026/4/17 --- **YAML (YAML Ain't Markup Language) 是一种以数据为中心、对人类友好的数据序列化语言。它因其简洁和高可读性而备受青睐，尤其是在配置文件和知识管理领域。** ### 1. YAML的应用场景 #### 作为Markdown知识笔记的元数据 ##### 什么是YAML Front Matter？ - **定义:** 它是添加到文件第一行的一系列纯文本属性，用于在Markdown等文件中添加元数据。 - **别称:** 也常被称为 front matter、页眉、前页、扉页、前言。 - **作用:** 它是一种人类可读、文件级的元数据，为笔记本身添加了结构化的信息，使得软件可以基于这些信息进行强大的自动化处理，例如分类、查询和筛选。 在Obsidian、Joplin等众多工具中，YAML Front Matter是核心功能。它为一篇笔记提供了超越其正文内容的“身份信息”。 **示例：** 在一篇Obsidian笔记的开头，你可以这样定义元数据。 ```yaml --- title: "我的Obsidian使用技巧" date: 2025-08-21 tags: [Obsidian, 知识管理, YAML] aliases: [Obsidian技巧, 如何使用Obsidian] --- ``` #### 作为AI提示词的格式 当构建复杂的AI提示词（Prompt）时，需要一种能够清晰组织指令、变量和上下文的格式。YAML在这方面表现出色。 | 格式 | 优点 | 缺点 | 适用场景 | | ------------ | ------------------------------------------------------------ | -------------------------------------- | -------------------------------------- | | **YAML** | 结构清晰，可读性高，易于手写和维护，适合表达复杂的层级关系。 | 语法依赖严格的缩进，对新手不友好。 | 复杂的、多参数的、需要模板化的AI任务。 | | **Markdown** | 自由流畅，接近自然语言，适合编写故事或对话型提示词。 | 结构性差，难以定义精确的配置参数。 | 文学创作、角色扮演、简单的问答。 | | **JSON** | 机器解析极为友好，语法严格，不易产生歧义，是API交互的标准。 | 手写繁琐，括号和引号过多，可读性较差。 | 程序化的API调用，自动化工作流。 | #### 作为配置文件 YAML是许多现代软件和工具首选的配置文件格式，因为它能清晰地表达复杂的配置结构。 - **智能家居自动化:** 在流行的开源智能家居平台 Home Assistant 中，用户主要通过编辑YAML文件（如 configuration.yaml）来设置自动化场景。例如，“当太阳下山时，自动打开客厅的灯”或者“当传感器检测到湿度低于40%时，开启加湿器”这样的规则，都是通过YAML来定义的。 - **PC游戏的插件与Mod:** 许多PC游戏（尤其是沙盒类游戏如《我的世界》Minecraft）的服务器插件或Mod，都使用YAML文件作为配置文件。服务器的管理员或玩家可以通过修改这些 .yml 文件，来调整游戏规则、设置商店物品价格、或者自定义玩家加入时的欢迎信息，而无需编写任何代码。 ### 2. YAML的基础语法 #### 核心规则 1. **格式**：采用“关键词: 值”的键值对形式（关键词 英文冒号 空格 值）。 样例： ```yaml views: - type: table name: 表格 order: - file.name - file.fullname - file.tags - file.folder ``` 2. **空格与缩进**：YAML 的语法对缩进和空格**极其敏感**，这是其结构的核心。理解并遵守这些规则是正确编写 YAML 的关键。 - **使用空格进行缩进**：通过空格缩进来表示数据的层级关系和嵌套。 - **严禁使用 Tab 键**：只能使用空格进行缩进，绝不能使用 Tab 键。混合使用或单独使用 Tab 键都会导致解析错误。 - **缩进需保持一致**：同一层级的元素必须左侧对齐（即保持相同的缩进量）。通常推荐使用 2 个或 4 个空格作为一级缩进。 - **冒号和短横线后的空格**： - 键值对的冒号 (:) 后面必须跟一个空格。 - 列表项的短横线 (-) 后面必须跟一个空格。 #### 基本数据结构 YAML 主要由三种基本数据结构组成：纯量（Scalars）、序列（Sequences/Lists）和映射（Mappings/Dictionaries）。 ##### 1. 纯量 (Scalars) 纯量是单个的、不可分割的值，是 YAML 中最基本的数据单元。 - **字符串 (String)** - 默认无需引号：my_string: Hello YAML - 单引号 (')：不会转义特殊字符，所有内容视为字面量。 - 双引号 (")：会转义特殊字符，例如 \n 会被解析为换行符。 - **数字 (Number)**：包括整数和浮点数。 - **布尔值 (Boolean)**：true 或 false。 - **空值 (Null)**：使用 null 或 ~ 表示。 **示例代码：** ```yaml # 字符串 string_value: Hello YAML quoted_string: "This is a string with a \n newline." # 数字 integer_value: 1024 float_value: 3.14159 # 布尔值 is_active: true is_enabled: false # 空值 empty_value: null another_empty: ~ ``` ##### 2. 序列 (Sequences / Lists) 序列是一组有序的值，类似于编程语言中的数组或列表。每个列表项由一个短横线 (-) 和一个空格开头。 **示例代码：** ```yaml # 一个简单的水果列表 fruits: - Apple - Orange - Strawberry # 也可以使用行内（inline）格式 fruits_inline: [Apple, Orange, Strawberry] ``` ##### 3. 映射 (Mappings / Dictionaries) 映射是键值对（key-value）的集合，类似于编程语言中的字典或哈希表。 **示例代码：** ```yaml # 描述一个用户的基本信息 user: name: John Doe age: 30 email: john.doe@example.com # 也可以使用行内（inline）格式 user_inline: {name: Jane Doe, age: 28} ``` #### 复合结构：数据嵌套 以上三种基本结构可以自由组合，形成复杂的数据结构。这是 YAML 强大功能的核心体现。 **示例代码：** ```yaml # 一个用户列表，每个用户都是一个包含详细信息的映射 users: # 第一个用户 - name: Alice age: 28 is_admin: true roles: # "roles" 的值是一个序列 - editor - publisher # 第二个用户 - name: Bob age: 35 is_admin: false roles: - viewer ``` #### 多行文本 **字面量块 `|`**：保留每一个换行。适合要“按原样呈现”的文本。 ```yaml about: | 第一行 第二行 第三行 ``` 解析后：`"第一行\n第二行\n第三行\n"`（注意末尾有 1 个换行，因为默认是clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）。 **折叠块** `>`：把换行折叠为空格（空行保留为换行） ```yaml about: > 这一段 被写成了多行 但会折叠成一行显示 空行用来分段 分段之间会出现真正的换行 ``` 解析后：`"这一段 被写成了多行 但会折叠成一行显示\n\n空行用来分段 分段之间会出现真正的换行\n"` （你看到：单个换行被折成空格；空行保留为 `\n`；末尾仍有一个换行，因为clip-保留一个结尾换行（\n），但丢掉多余的尾随空行） #### 注释 使用井号 (#) 进行单行注释。从 # 开始到该行末尾的所有内容都会被忽略。 ```yaml # 这是一个注释，它将被解析器忽略。 key: value # 这也是一个行内注释。 ``` ### 3. YAML在Obsidian中的实践 在Obsidian中，YAML元数据是实现知识库从简单笔记集合升级为强大个人数据库的关键。它为每篇笔记赋予了结构化的“属性”，使得自动化管理和知识发现成为可能。 #### 从YAML Front Matter到“属性”视图 最初，YAML元数据需要手动在笔记顶端的`---`分隔符之间编写。为了降低使用门槛并提升体验，Obsidian推出了核心的“**属性**”（Properties）功能。 * **可视化界面**：你不再需要手动输入YAML代码，可以通过一个直观的界面在笔记顶部添加、编辑或删除属性。这个界面提供了文本、数字、日期、复选框和列表等多种属性类型，并会自动补全已存在的属性名和值，极大地保证了数据的一致性。 * **源码对应**：你在属性界面上的所有操作，都会实时、准确地转换成笔记源文件顶部的标准YAML Front Matter。你随时可以切换到“源码模式”查看和编辑底层的YAML代码。 #### Obsidian原生支持的特殊属性 Obsidian会对一些特定的YAML属性赋予特殊功能，让它们与软件的核心功能深度集成。 | 属性 (Property) | 功能描述 (Description) | 格式要求 (Format Requirement) | | :--- | :--- | :--- | | `tags` | 定义笔记的标签，会自动被Obsidian的“标签面板”识别和索引。 | 必须是列表（Array）格式。 | | `aliases` | 为笔记设置一个或多个“别名”，方便通过别名进行链接和搜索。 | 必须是列表（Array）格式。 | | `cssclasses` | 为当前笔记应用一个或多个自定义的CSS样式片段，实现特定的视觉效果。 | 必须是列表（Array）格式。 | > **重要更新**：从Obsidian 1.4版本开始，官方统一并强制要求这些原生属性必须使用复数形式（`tags`, `aliases`, `cssclasses`），并且它们的值必须是列表格式。 #### 设计你的个人化元数据系统 YAML的真正威力在于自定义。通过建立一套规范的元数据体系，你可以为自己的知识库量身打造强大的分类和检索系统。 | 实践建议 (Practice) | 目的与描述 (Purpose & Description) | 示例 (Example) | | :--- | :--- | :--- | | **规范命名** | 为了便于Dataview等插件查询，建议属性名全部使用小写，并用下划线代替空格。 | `creation_date` | | **笔记分类** | 使用`type`或`category`属性来定义笔记的类型，这是进行分类查询的基础。 | `type: book` | | **状态追踪** | 使用`status`属性来管理笔记的生命周期或项目的进度。 | `status: seedling` (想法) | | **建立关联** | 除了使用`[[链接]]`，你还可以用属性来定义更明确的关系。 | `author: [[作者A]]` | #### 通过Obsidian插件，让你的元数据“活”起来 你精心维护的YAML属性，通过插件可以实现知识的自动化组织与呈现。 | 插件 (Plugin) | 核心功能 (Core Function) | 应用实例 (Application Example) | | :--- | :--- | :--- | | **Dataview** | 使用简单的查询语言（DQL）从整个知识库中筛选、排序和展示笔记，自动生成动态的笔记列表和表格。 | 创建一个“动态首页”，自动汇总所有 `status: in-progress` 的任务。 | | **Bases** | (官方插件) 提供一个可视化的、类似Notion数据库的界面（表格、看板等）来浏览和批量编辑笔记的元数据。 | 以看板视图来管理所有 `type: project` 的笔记，并拖动卡片来改变它们的 `status` 属性。 | | **Metadata Menu** | 极大地增强了属性的编辑体验，可以为属性预设可选值或创建依赖关系，实现更高效、规范的元数据录入。 | 为`status`属性设置固定的下拉菜单选项："待办"、"进行中"、"完成"。 | ### 4. YAML的编辑器或格式化工具 | 工具 | 类型 | 主要功能 | | ----------------------- | -------------- | ------------------------------------------------------------------ | | **VS Code + YAML 插件** | 桌面编辑器 | 语法高亮、自动补全、实时错误校验、代码折叠、格式化。 | | **Online YAML Parsers** | 在线工具，例如[YAML Checker - The YAML Syntax Validator](https://yamlchecker.com/) | 快速验证YAML语法是否正确，进行格式化和美化，适合临时检查。 | | **Prettier** | 代码格式化工具，例如[Prettier · Opinionated Code Formatter · Prettier](https://prettier.io/) | 通过插件支持YAML，可以在项目中统一代码风格，实现保存时自动格式化。 |