yaml

file: all-data.yaml

name: development port: 3000

name: production port: 80 ...

第三个文档：列表

• item1
• item2

解析这样的文件时，标准 YAML 库通常会返回一个文档迭代器或列表，每个文档需要单独处理。这对于批量数据很实用，但它仅仅是“物理合并在一个文件里”，并非逻辑组合。对于配置管理，我们更需要的是**跨文件的引用与合并**。

#### 2.2 手动使用工具分割/拼接文档

借助 `yq`（类似 jq 的 YAML 处理工具）可以轻松拆分和合并多个文档。

```bash
# 提取第一个文档
yq eval 'select(di == 0)' all-data.yaml

# 将多个文件拼接成一个多文档流
yq eval-all '.' file1.yaml file2.yaml

但这依然属于辅助操作，真正优雅的多文件管理需要更高级的机制。

三、跨文件引用与组合：以工具为核心

现代工具生态提供了多种实现多文件组合的方式，核心思想是“定义基座，按环境/模块覆盖”。

3.1 Docker Compose 的多文件组合

Docker Compose 是经典案例。它允许通过 -f 指定多个 Compose 文件，后续文件中的配置会覆盖前面文件中的相同键。

基础文件 docker-compose.base.yml：

version: '3.8'
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    environment:
      - NODE_ENV=development

环境差异文件 docker-compose.prod.yml：

version: '3.8'
services:
  web:
    image: nginx:stable
    ports:
      - "443:443"
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=error
    restart: always

启动时合并：

docker compose -f docker-compose.base.yml -f docker-compose.prod.yml up

合并逻辑：以深度合并的方式，prod 文件的字段会覆盖 base 的相同字段，同时保留未提及的字段。最终的服务配置将是 base 的补充与覆盖。

实用原则：

• 基础文件定义通用骨架。
• 差异文件只写变化部分，保持极简。
• 通过多个 -f 可以形成继承链，如 base → staging → prod 逐步叠加。

3.2 Ansible 的多文件组织

Ansible 通过角色和目录结构实现多文件管理，变量分散在多个位置并按优先级合并：

playbook.yml
group_vars/
  all.yml          # 全部主机通用
  webservers.yml   # webservers 组专用
host_vars/
  host1.yml        # 特定主机覆盖
roles/
  web/
    defaults/      # 角色默认变量（最易被覆盖）
    vars/          # 角色固定变量（较高优先级）

这些 YAML 文件在运行时会被自动加载并合并。例如 Playbook 中不必显式 import，变量天然跨文件生效：

# group_vars/all.yml
app_user: app
log_level: info

# group_vars/webservers.yml
log_level: debug

当某台主机属于 webservers 组时，最终 log_level 为 debug，因为组变量优先级高于 all。这种组织方式让大规模配置管理成为可能。

3.3 Helm Chart 的模板化与 values 复用

在 Kubernetes 生态中，Helm Chart 将多文件组织推向极致：模板与值分离。

• Chart.yaml：元数据
• values.yaml：默认配置值
• templates/：包含引用 .Values 对象的模板
• 自定义 values 文件：values-prod.yaml

部署时通过 -f 指定多个 values 文件实现合并覆盖：

helm install myapp ./mychart -f values.yaml -f values-prod.yaml

多个 values 文件的合并在 Helm 中采用了深度合并，后指定的文件优先级更高。这完美支持了“公共基础配置 + 环境个性化”的模式。

3.4 Kustomize：声明式多文件覆盖与修补

Kustomize 是 Kubernetes 原生的配置定制工具，完全基于 YAML 多文件组织，无需模板。它通过 kustomization.yaml 指定资源、补丁、生成器等。

目录结构示例：

base/
  deployment.yaml
  service.yaml
  kustomization.yaml
overlays/
  production/
    deployment-patch.yaml
    kustomization.yaml

在 base 中定义通用资源，在 overlay 中通过 patchesStrategicMerge 添加或修改字段。最终运行 kubectl kustomize overlays/production 会生成合并后的完整资源清单。

这种方式尤其适合多环境管理，且完全保留 YAML 原生语法，易于理解和版本控制。

四、亲手实现轻量级多文件合并

如果项目不依赖上述大型工具，你也可以用通用 YAML 处理工具实现自定义合并。

4.1 使用 yq 合并多个文件

yq (https://github.com/mikefarah/yq) 是一个强大的命令行 YAML 处理器。其 eval-all 支持将多个文件的内容进行深度合并。

例如有 base.yaml 和 dev.yaml：

# 深度合并，dev.yaml中的键覆盖base.yaml中的同路径键
yq eval-all '. as $item ireduce ({}; . * $item )' base.yaml dev.yaml

或者更简洁的写法（yq 版本 4.18+）：

yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml dev.yaml

这会将两个文件的内容合并，第二个文件中的值优先。

4.2 使用 Python 实现定制合并逻辑

如果内置合并策略不满足需求，可以通过 Python 的 PyYAML 库编写脚本。

import yaml

def deep_merge(base, override):
    """递归合并字典，override中的值优先"""
    if isinstance(base, dict) and isinstance(override, dict):
        for key, value in override.items():
            if key in base:
                base[key] = deep_merge(base[key], value)
            else:
                base[key] = value
        return base
    return override

files = ['base.yaml', 'merge.yaml']
merged = {}
for file in files:
    with open(file) as f:
        merged = deep_merge(merged, yaml.safe_load(f) or {})
print(yaml.dump(merged))

这种方案适合需要定制逻辑的场景，例如列表采用追加而非覆盖，或者对敏感键做特殊处理。

五、多文件组织的最佳实践与策略

多文件拆分容易，但维护有序的拆分是一门学问。

5.1 按关注点拆分，而非随意剪切

常见的拆分维度有：

• 按环境：base.yaml + dev.yaml + prod.yaml
• 按组件：database.yaml、redis.yaml、logging.yaml
• 按作用域：global.yaml、service-web.yaml、service-worker.yaml

建议结合二者，形成层次化目录：

config/
  base/
    global.yaml
    database.yaml
  overlays/
    dev/
      patches.yaml
    prod/
      patches.yaml

这样既隔离了环境特有配置，又保持了组件的内聚。

5.2 使用明确的命名约定和版本控制

• 文件命名语义化：application.base.yml、application.dev.override.yml。
• 将多文件视为整体存储于 Git 同一个仓库，便于追踪变更历史。
• 避免在子文件中重复定义基础文件中已存在且不变的内容，减少冗余。

5.3 测试合并后的结果

在 CI/CD 或本地脚本中，始终验证合并后的最终 YAML 是有效的。

# 合并后输出到 stdout 并检查是否合法 YAML
yq eval-all '...' base.yaml dev.yaml | yq eval -o=yaml . > expected.yaml
# 如果语法错误，yq 会报错

一些工具提供了 dry-run 输出，可以利用这些输出来审查最终配置。

5.4 善用锚点和别名避免重复（内部复用）

YAML 内部支持锚点(&)和别名(*)以及合并键(<<:)，可以在单文件或多文件合并后使用。但注意：锚点和别名不能跨文件引用。因此结合多文件时，通常利用工具在合并后使用这些特性，或在基础文件中定义锚点，由工具合并后再解析。

例如在基础文件定义通用配置块：

definitions:
  - &default_log
    level: info
    format: json

service_a:
  logging: *default_log
service_b:
  logging:
    <<: *default_log
    level: debug      # 局部覆盖