Docker-YAML配置文件语法

YAML配置文件语法详解 (2026年03月27日)

YAML简介

YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化语言，广泛用于配置文件、数据交换等场景。YAML的设计目标是易于阅读和编写，同时能够表示复杂的数据结构。它是JSON的超集，支持注释、多行字符串、引用等高级特性。

基本语法规则

1. 缩进

YAML使用空格缩进表示层级关系（不使用Tab）：

# 正确：使用2空格缩进
server:
  port: 8080
  host: localhost

# 错误：使用Tab缩进
server:
	port: 8080
​

2. 注释

# 这是单行注释
server:
  port: 8080  # 行尾注释

# 多行注释需要每行加#
# 第二行注释
# 第三行注释
​

3. 文档开始和结束

---  # 文档开始标记
server:
  port: 8080
...  # 文档结束标记

# 一个文件可以包含多个文档
---
document: 1
---
document: 2
...
​

数据类型

1. 标量（Scalar）

字符串

# 简单字符串
name: John Doe

# 单引号字符串（不转义）
message: 'Hello\nWorld'  # 输出：Hello\nWorld

# 双引号字符串（转义）
message: "Hello\nWorld"  # 输出：Hello + 换行 + World

# 多行字符串（保留换行）
description: |
  This is a
  multi-line
  string.

# 多行字符串（折叠换行）
description: >
  This is a single
  line string.
​

数字

# 整数
count: 42
negative: -10

# 浮点数
price: 19.99
scientific: 1.23e4

# 其他数字表示
octal: 0o14      # 八进制
hex: 0x2A        # 十六进制
​

布尔值

enabled: true
disabled: false
# 也可以使用yes/no
active: yes
inactive: no
​

空值

empty: null
# 或使用~
another_empty: ~
# 或不写值
blank:
​

2. 数组（List/Sequence）

块风格

# 使用短横线（-）表示数组元素
fruits:
  - apple
  - banana
  - orange

# 嵌套数组
matrix:
  - [1, 2, 3]
  - [4, 5, 6]
​

流风格

# 使用方括号表示数组
numbers: [1, 2, 3, 4]
​

3. 对象（Map/Dictionary）

块风格

person:
  name: John
  age: 30
  city: New York
​

流风格

person: { name: John, age: 30, city: New York }
​

高级特性

1. 锚点和别名（Anchor & Alias）

# 定义锚点（&）
defaults: &defaults
  adapter: postgres
  host: localhost

# 引用锚点（*）
development:
  database:
    <<: *defaults  # 继承defaults的所有属性
    port: 5432

production:
  database:
    <<: *defaults
    host: prod.example.com
    port: 5433
​

2. 类型转换

# 显式指定类型
age: !!str 123  # 数字转为字符串
date: !!timestamp 2026-03-27
​

3. 多文档

---
document: 1
version: v1
---
document: 2
version: v2
...
​

实际应用示例

1. Kubernetes配置

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
        env:
        - name: ENV
          value: "production"
​

2. Docker Compose配置

# docker-compose.yml
version: '3.8'

services:
  web:
    build: .
    ports:
      - "8080:80"
    environment:
      - DEBUG=false
      - DB_HOST=db
    depends_on:
      - db
    networks:
      - frontend
  
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: example
      POSTGRES_DB: myapp
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db-data:

networks:
  frontend:
  backend:
​

3. 应用配置文件

# config.yaml
app:
  name: MyApp
  version: 1.0.0
  debug: true

server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert: /path/to/cert.pem
    key: /path/to/key.pem

database:
  default:
    driver: postgres
    host: localhost
    port: 5432
    name: myapp
    username: user
    password: password
    pool:
      min: 5
      max: 20
    timeout: 30

logging:
  level: info
  format: json
  outputs:
    - type: console
      colorize: true
    - type: file
      path: /var/log/app.log
      rotation: daily
      retention: 30

features:
  cache:
    enabled: true
    ttl: 3600
  rate-limit:
    enabled: true
    requests-per-minute: 100
​

4. GitHub Actions配置

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x]
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run tests
      run: npm test
    
    - name: Build
      run: npm run build
​

YAML最佳实践

1. 保持一致性

   • 在整个项目中使用相同的缩进风格（2空格或4空格）
   • 对相似的数据结构使用相同的格式

2. 使用注释

   • 为复杂的配置添加注释说明
   • 解释为什么这样配置，而不是配置了什么

3. 避免深度嵌套

   • 超过3层嵌套会降低可读性
   • 考虑使用锚点和别名减少重复

4. 使用引号

   • 当值可能被误读时使用引号
   • 例如："yes", "true", "123"

5. 验证YAML

   • 使用在线工具或命令行工具验证语法
   • yamllint是流行的YAML语法检查工具

6. 版本控制

   • 对配置文件进行版本控制
   • 记录配置变更的原因

常见错误

1. 使用Tab缩进：YAML只允许使用空格
2. 引号不匹配：确保引号成对出现
3. 特殊字符未转义：如:、[、]等
4. 缩进不一致：同一层级必须使用相同缩进
5. 多行字符串格式错误：注意|和>的区别

工具推荐

1. 编辑器插件

   • VS Code: YAML Language Support
   • IntelliJ IDEA: 内置YAML支持

2. 验证工具

   • yamllint: pip install yamllint
   • 在线验证器: yaml-online-parser.appspot.com

3. 转换工具

   • YAML转JSON: yamldata.com
   • YAML转TOML: toml.io

YAML作为现代配置文件的首选格式，其可读性和表达能力使其成为DevOps、应用开发等领域的重要工具。