YAML 语言教程

作者: 阮一峰

日期: 2016年7月 4日

编程免不了要写配置文件,怎么写配置也是一门学问。

YAML 是专门用来写配置文件的语言,非常简洁和强大,远比 JSON 格式方便。

本文介绍 YAML 的语法,以 JS-YAML 的实现为例。你可以去在线 Demo 验证下面的例子。

一、简介

YAML 语言(发音 /ˈjæməl/ )的设计目标,就是方便人类读写。它实质上是一种通用的数据串行化格式。

它的基本语法规则如下。

  • 大小写敏感
  • 使用缩进表示层级关系
  • 缩进时不允许使用Tab键,只允许使用空格。
  • 缩进的空格数目不重要,只要相同层级的元素左侧对齐即可

# 表示注释,从这个字符一直到行尾,都会被解析器忽略。

YAML 支持的数据结构有三种。

  • 对象:键值对的集合,又称为映射(mapping)/ 哈希(hashes) / 字典(dictionary)
  • 数组:一组按次序排列的值,又称为序列(sequence) / 列表(list)
  • 纯量(scalars):单个的、不可再分的值

以下分别介绍这三种数据结构。

二、对象

对象的一组键值对,使用冒号结构表示。


animal: pets

转为 JavaScript 如下。


{ animal: 'pets' }

Yaml 也允许另一种写法,将所有键值对写成一个行内对象。


hash: { name: Steve, foo: bar } 

转为 JavaScript 如下。


{ hash: { name: 'Steve', foo: 'bar' } }

三、数组

一组连词线开头的行,构成一个数组。


- Cat
- Dog
- Goldfish

转为 JavaScript 如下。


[ 'Cat', 'Dog', 'Goldfish' ]

数据结构的子成员是一个数组,则可以在该项下面缩进一个空格。


-
 - Cat
 - Dog
 - Goldfish

转为 JavaScript 如下。


[ [ 'Cat', 'Dog', 'Goldfish' ] ]

数组也可以采用行内表示法。


animal: [Cat, Dog]

转为 JavaScript 如下。


{ animal: [ 'Cat', 'Dog' ] }

四、复合结构

对象和数组可以结合使用,形成复合结构。


languages:
 - Ruby
 - Perl
 - Python 
websites:
 YAML: yaml.org 
 Ruby: ruby-lang.org 
 Python: python.org 
 Perl: use.perl.org 

转为 JavaScript 如下。


{ languages: [ 'Ruby', 'Perl', 'Python' ],
  websites: 
   { YAML: 'yaml.org',
     Ruby: 'ruby-lang.org',
     Python: 'python.org',
     Perl: 'use.perl.org' } }

五、纯量

纯量是最基本的、不可再分的值。以下数据类型都属于 JavaScript 的纯量。

  • 字符串
  • 布尔值
  • 整数
  • 浮点数
  • Null
  • 时间
  • 日期

数值直接以字面量的形式表示。


number: 12.30

转为 JavaScript 如下。


{ number: 12.30 }

布尔值用truefalse表示。


isSet: true

转为 JavaScript 如下。


{ isSet: true }

null~表示。


parent: ~ 

转为 JavaScript 如下。


{ parent: null }

时间采用 ISO8601 格式。


iso8601: 2001-12-14t21:59:43.10-05:00 

转为 JavaScript 如下。


{ iso8601: new Date('2001-12-14t21:59:43.10-05:00') }

日期采用复合 iso8601 格式的年、月、日表示。


date: 1976-07-31

转为 JavaScript 如下。


{ date: new Date('1976-07-31') }

YAML 允许使用两个感叹号,强制转换数据类型。


e: !!str 123
f: !!str true

转为 JavaScript 如下。


{ e: '123', f: 'true' }

六、字符串

字符串是最常见,也是最复杂的一种数据类型。

字符串默认不使用引号表示。


str: 这是一行字符串

转为 JavaScript 如下。


{ str: '这是一行字符串' }

如果字符串之中包含空格或特殊字符,需要放在引号之中。


str: '内容: 字符串'

转为 JavaScript 如下。


{ str: '内容: 字符串' }

单引号和双引号都可以使用,双引号不会对特殊字符转义。


s1: '内容\n字符串'
s2: "内容\n字符串"

转为 JavaScript 如下。


{ s1: '内容\\n字符串', s2: '内容\n字符串' }

单引号之中如果还有单引号,必须连续使用两个单引号转义。


str: 'labor''s day' 

转为 JavaScript 如下。


{ str: 'labor\'s day' }

字符串可以写成多行,从第二行开始,必须有一个单空格缩进。换行符会被转为空格。


str: 这是一段
  多行
  字符串

转为 JavaScript 如下。


{ str: '这是一段 多行 字符串' }

多行字符串可以使用|保留换行符,也可以使用>折叠换行。


this: |
  Foo
  Bar
that: >
  Foo
  Bar

转为 JavaScript 代码如下。


{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }

+表示保留文字块末尾的换行,-表示删除字符串末尾的换行。


s1: |
  Foo

s2: |+
  Foo


s3: |-
  Foo

转为 JavaScript 代码如下。


{ s1: 'Foo\n', s2: 'Foo\n\n\n', s3: 'Foo' }

字符串之中可以插入 HTML 标记。


message: |

  <p style="color: red">
    段落
  </p>

转为 JavaScript 如下。


{ message: '\n<p style="color: red">\n  段落\n</p>\n' }

七、引用

锚点&和别名*,可以用来引用。


defaults: &defaults
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  <<: *defaults

test:
  database: myapp_test
  <<: *defaults

等同于下面的代码。


defaults:
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  adapter:  postgres
  host:     localhost

test:
  database: myapp_test
  adapter:  postgres
  host:     localhost

&用来建立锚点(defaults),<<表示合并到当前数据,*用来引用锚点。

下面是另一个例子。


- &showell Steve 
- Clark 
- Brian 
- Oren 
- *showell 

转为 JavaScript 代码如下。


[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]

八、函数和正则表达式的转换

这是 JS-YAML 库特有的功能,可以把函数和正则表达式转为字符串。


# example.yml
fn: function () { return 1 }
reg: /test/

解析上面的 yml 文件的代码如下。


var yaml = require('js-yaml');
var fs   = require('fs');

try {
  var doc = yaml.load(
    fs.readFileSync('./example.yml', 'utf8')
  );
  console.log(doc);
} catch (e) {
  console.log(e);
}

从 JavaScript 对象还原到 yaml 文件的代码如下。


var yaml = require('js-yaml');
var fs   = require('fs');

var obj = {
  fn: function () { return 1 },
  reg: /test/
};

try {
  fs.writeFileSync(
    './example.yml',
    yaml.dump(obj),
    'utf8'
  );
} catch (e) {
  console.log(e);
}

九、参考链接

(完)

留言(80条)

学symfony的时候一直没去学yaml的语法, 看了这篇文章,感觉清晰不少

六条 最后一例的解析结果 message: '\n<p style="color: red">\n 段落\n</p>\n' }

我明白了 是网页显示不出来 需要转义...

Hexo 就是用 yaml 组织配置文件。

内容是 YAML 语言,图片确是 YAML CSS framework 的。

@weet:

谢谢指出,已经换过图片了。

@mrsu:

谢谢指出,已经对 HTML 标签转义了。

YAML有办法进行字符串拼接吗?比如先定义了一个基本的配置 host: xxxx,然后下面有几个配置要跟这个host接接在一起。总不能还在要程序里拼接一次吧?

引用skip的发言:

YAML有办法进行字符串拼接吗?比如先定义了一个基本的配置 host: xxxx,然后下面有几个配置要跟这个host接接在一起。总不能还在要程序里拼接一次吧?

好像可以使用 %{parameter} 进行拼接

最烦缩进表示语法了

引用Alex的发言:

最烦缩进表示语法了

非常同意!

引用Cheng的发言:

好像可以使用 %{parameter} 进行拼接

能否举个例子,感谢!

阮老师,希望能写一篇关于RxJs,可扩展式的编程开发理念,用法和实际的应用场景。
github上面也有1W个星,演示的demo也很强大,而且还是家族系列。
可是为什么就是感觉不温不火的。

不应该是Yet Another Markup Language吗?

第八节函数转换的例子,应该使用


fn: !!js/function function () { return 1 }

但是貌似只能使用js内置函数,毕竟有作用域的问题。

S-表达式是最好的数据格式!

引用Joe的发言:

不应该是Yet Another Markup Language吗?

Yaml Ain't a Markup Language, 跟json是一类的.

一直以来,从阮老师的博文学习了不少知识。刚无意中翻看了很多阮老师的文章,看到了你小额支付的试验结果,看到了你与百姓网ceo关于为什么要写博文的讨论,看到你说希望通过博文与大家交流......终于静默不住,所以翻到最新的一页博文下,来给你留言。我是一个菜鸟,看博文的过程中,能力有限,无法留言技术相关的东西,因而一直沉默着。但是,内心一直对于你给予的贡献和帮助,非常感谢!我相信由于同样原因沉默的肯定不止我一人,其实我想说的是,很多人都在这里。

引用cherish的发言:

一直以来,从阮老师的博文学习了不少知识。刚无意中翻看了很多阮老师的文章,看到了你小额支付的试验结果,看到了你与百姓网ceo关于为什么要写博文的讨论,看到你说希望通过博文与大家交流......终于静默不住,所以翻到最新的一页博文下,来给你留言。我是一个菜鸟,看博文的过程中,能力有限,无法留言技术相关的东西,因而一直沉默着。但是,内心一直对于你给予的贡献和帮助,非常感谢!我相信由于同样原因沉默的肯定不止我一人,其实我想说的是,很多人都在这里。

是的 比如我也是 哈哈 阮老师 加油

规则竟然如此sb
大小写敏感
使用缩进表示层级关系
缩进时不允许使用Tab键,只允许使用空格。
缩进的空格数目不重要,只要相同层级的元素左侧对齐即可

一如既往的简洁明了

计算机语言实在是太多了,学不完啊,YAML第一次听说。

通俗易懂,点滴间展现了老师的深厚功底,佩服~

瞬间感觉知识不够用呀,太厉害了

很好的教程,正好用到这yml配置文件,支持一下

首先,让我先表达一下对您的敬佩,您是我学习的榜样。
除了用Yaml和Json和ini文件做配置,好象还要以使用Toml,这个可能更适合一些。
Yaml规范太复杂,Json相对简单,但不能写注释。
Toml很好,可以参考一下。

阮老师,第一次在您博客留言,但是已经看了您很多文章。很清晰,也帮助了我很多,特此留言表示感谢之情。嘿嘿

Hexo的配置文件就是YAML格式的,第一次改配置就感觉简单明了。
用空格缩进不能使用Tab,哈哈哈,这点做得好,阻碍Python初学者的一个原因就是混用空格Tab引起的问题

一直想学习yaml,阮大师写的清晰明了

我怎么觉得还不如json简单易懂呢

阮大师,我是个做JAVA开发的工作两年了,最近一份工作是做PAAS,关注服务器端比较多,慢慢的代码也开始生疏了,但我还想继续JAVA学习,觉得迷茫。能给写建议吗。

很不錯的教學

目前写的最多的配置文件是webpack配置,其他的还没接触过,暂时用不上yaml,以后项目大了之后,再来看吧

系列文章都是这么的深入浅出,厉害,佩服!!!

hexo的_config.yml文件似乎不支持嵌入HTML标记呢。

引用张三的发言:

规则竟然如此sb
大小写敏感
使用缩进表示层级关系
缩进时不允许使用Tab键,只允许使用空格。
缩进的空格数目不重要,只要相同层级的元素左侧对齐即可

我也觉得是个sb的格式...
感觉不如ini,或者readline...

不过,什么东西都会有工具的

阮老师,我刚刚照着您的例子跑了一下,我用的js-yaml版本是3.6.1。

发现那个导入函数和正则的例子,需要写成下面的形式,才能导入成函数和正则对象吧,如果在值的前面不通过

!!
声明类型,那么直接导入成字符串了。

# example.yml
fn: !!js/function function () { return 1}
reg: !!js/regexp  /test/

引用张三的发言:

规则竟然如此sb
大小写敏感
使用缩进表示层级关系
缩进时不允许使用Tab键,只允许使用空格。
缩进的空格数目不重要,只要相同层级的元素左侧对齐即可

yaml用于展现或编辑具有层级关系的数据非常非常好

“大小写敏感” 是为了大小写敏感的语言进行序列化和反序列化

“使用缩进表示层级关系” 是为了在编辑器里能把层级关系看得清清楚楚

“缩进时不允许使用Tab键,只允许使用空格” 一是为了保证在解析数据时层级关系的准确,二是为了在不同的编辑器里不会因 tab 的占居空格不同而显示为不同的层级关系

“缩进的空格数目不重要,只要相同层级的元素左侧对齐即可” 计算机解析时只需要计算缩进空格数的相等与否,而因人视力的不同,有人能清楚的看出2格缩进,有人却需要8格

举例说明:
项目的菜单以配置文件的方式保存,随着项目功能代码的变化,需要频繁同步做菜单名称的修改,子菜单项的添加、删除、移动(调整顺序或变换父级菜单)。

这种场景无论是用xml、json、ini或其他格式,都是会一件非常痛苦的事情,使用 yaml 后,一切变得 easy,编辑的时候看得清清楚楚,修改的时候方便又明晰,程序读取的时候,直接反序化为对象输出。


非常受用,总能在阮老师的网页找到有用的文章,望再接再厉!

引用大头的发言:

我怎么觉得还不如json简单易懂呢

我也觉得

引用Joe的发言:

不应该是Yet Another Markup Language吗?

这样的话就不递归了呀......

这篇文章写的很好,简单明了,非常喜欢。最近在试用YAML时遇到一个小问题,找到原因后来分享下,就是锚点&名称里不能有下划线,否则引用失败。

你好请问下yaml如何定义变量 并且引用变量

看了很多英文的材料都没有你写的好

如果返回值只有字符串“true”,而不是json格式的字符串,应该怎么写校验?

@zhouzm:

我也觉得这种简洁规整的语法好,很清晰,而且和他人合作时也不会混乱。懒得打这么多字去解释,正好看到您的回复,顶一下表示支持。

大多数.yml文件开头都是三个横线, 像这样:


---
YAML: YAML Ain't Markup Language

请问其中有什么含义?

竟然和python风格如此相似,很容易理解,不错

串行化应该是序列化吧,感觉翻译的不准确

描述中写道“双引号不会对特殊字符转义”,这个是否应该是单引号?

yaml 我在spring boot 看到了,特来学习。

最近在写ansible学习笔记,用到yaml,一搜索,果然前排就是阮大文章,看完收益良多

引用8023的发言:

大多数.yml文件开头都是三个横线, 像这样:

---
YAML: YAML Ain't Markup Language

请问其中有什么含义?

在单一文件中,可用连续三个连字号(---)区分多个文件。
另外,还有选择性的连续三个点号( ... )用来表示文件结尾。
摘选自 https://zh.wikipedia.org/wiki/YAML

有点繁琐。简单的还行,点有点多,复杂点就很容易误解了

yaml层级关系和Python类似,都是用缩进表示,而不是像别的语言用括号或者标签来表示。

引用张三的发言:

规则竟然如此sb
大小写敏感
使用缩进表示层级关系
缩进时不允许使用Tab键,只允许使用空格。
缩进的空格数目不重要,只要相同层级的元素左侧对齐即可

怕是被 windows 毒害的开发者

@zhouzm:

同意。感觉yaml的卖点就是对人类友好,尽可能符合人类书写和阅读的习惯。

2个文件怎么根据不同merge成一个文件

同意。感觉yaml的卖点就是对人类友好,尽可能符合人类书写和阅读的习惯。

yaml 的语法真的是个性,和其他的都不怎么一样!

确实不如json易懂。 json更合适

真的 在google搜大部分技术资料都可以搜到阮老师的。佩服

我配置的这个,filterMap1: { "/login": anon, /toLogin: anon} 注入结果却是 filterMap1: {login=anon, toLogin=anon}

阮老师,为什么key中的/和* 全部被过滤掉了

引用Jacob的发言:

Yaml Ain't a Markup Language, 跟json是一类的.

维基百科是这么说的,YAML是"YAML Ain't a Markup Language"(YAML不是一种标记语言)的递归缩写。在开发的这种语言时,YAML 的意思其实是:"Yet Another Markup Language"(仍是一种标记语言)[3],但为了强调这种语言以数据做为中心,而不是以标记语言为重点,而用反向缩略语重命名。

引用千发的发言:

确实不如json易懂。 json更合适

YAML is a superset of JSON!

引用Cheng的发言:

好像可以使用 %{parameter} 进行拼接


试了,并不行!

大师,想请教一下如何是用代码来设置锚点和引用

单引号会解析字符串中的\
双引号不会解析字符串中的\
s1: '内容\n字符串'
s2: "内容\n字符串"
转换为Javascript得应该时这样:
{
s1:'内容\n字符串',
s2: '内容\\n字符串'
}
Javascript中\代表不解析后面的斜杠

引用陈耀军的发言:

首先,让我先表达一下对您的敬佩,您是我学习的榜样。
除了用Yaml和Json和ini文件做配置,好象还要以使用Toml,这个可能更适合一些。
Yaml规范太复杂,Json相对简单,但不能写注释。
Toml很好,可以参考一下。

JSON5 了解一下,能写注释;

常用部分,简洁清晰!

最不喜欢的就是缩进语法,逆天的操作

YAML 作为配置文件应用范围很广啊,k8S、gitlab、ansible

请问一下
--- {}
三个横杠之后还有花括号,这是什么意思呢

阮老师,关于引用这一部分,从YAML 1.2规范文档中并我未找到

抑或是多数编辑器、解释器增加的一种新特性支持呢?

讲得十分清晰,谢谢老师

阮老师您好!
首选感叹一下同为姓阮能够在这里相遇,深感荣幸!更赞叹于你的技术分享,细致清晰易理解,看了5-6篇关于YAML语法的博文,只有您这篇相对全而且易理解。非常感谢!

学到docker,看不懂docker-compose配置文件,过来学一下YAML

YAML通用的数据串行化格式配置文件语言方便读写。

yaml比json更难懂,居然还可以写函数,太复杂了。

对列表对象怎么锚点呢?

引用caoyy的发言:

描述中写道“双引号不会对特殊字符转义”,这个是否应该是单引号?

没错,描述不太清晰。双引号会转义字符,和C语言一样

我要发表看法

«-必填

«-必填,不公开

«-我信任你,不会填写广告链接