yq-yaml-processing

yq YAML 处理

使用 yq v4+ 处理、查询和转换 YAML 数据的专业知识。yq 是一款轻量级命令行 YAML 处理器，采用类似 jq 的语法。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他技能……
查询或修改 YAML 文件	输入仅包含 JSON — 使用 jq-json-processing
在保留注释和键顺序的同时就地编辑 YAML	涉及 YAML、JSON、CSV、TOML 的多步骤转换 — 使用 nushell-data-processing
有针对性地更新 Kubernetes 清单或 Actions 工作流	完整的 Kubernetes 管理（使用 kubectl）；XML（使用 xmlstarlet）
合并 YAML 配置	聚合或分组多个文件中的数据 — 使用 nushell-data-processing

核心专长

YAML 操作

• 使用路径表达式查询和筛选 YAML
• 转换 YAML 结构和形态
• 支持多文档 YAML
• 在 YAML、JSON、XML 和其他格式之间转换

配置管理

• 修改 Kubernetes 清单
• 更新 GitHub Actions 工作流
• 处理 Helm values 文件
• 管理应用配置

基本命令

基本查询

# Pretty-print YAML
yq '.' file.yaml

# Extract specific field
yq '.fieldName' file.yaml

# Extract nested field
yq '.spec.containers[0].name' pod.yaml

# Access array element
yq '.[0]' array.yaml
yq '.items[2]' data.yaml

读取 YAML

# Read specific field
yq '.metadata.name' deployment.yaml

# Read nested structure
yq '.spec.template.spec.containers[].image' deployment.yaml

# Read with default value
yq '.optional // "default"' file.yaml

# Check if field exists
yq 'has("fieldName")' file.yaml

修改 YAML（就地）

# Update field value
yq -i '.metadata.name = "new-name"' file.yaml

# Update nested field
yq -i '.spec.replicas = 3' deployment.yaml

# Add new field
yq -i '.metadata.labels.app = "myapp"' file.yaml

# Delete field
yq -i 'del(.spec.nodeSelector)' file.yaml

# Append to array
yq -i '.items += {"name": "new-item"}' file.yaml

# Update all matching elements
yq -i '(.items[] | select(.name == "foo")).status = "active"' file.yaml

多文档 YAML

# Split multi-document YAML
yq -s '.metadata.name' multi-doc.yaml

# Select specific document (0-indexed)
yq 'select(document_index == 0)' multi-doc.yaml

# Process all documents
yq eval-all '.' multi-doc.yaml

# Filter documents
yq 'select(.kind == "Deployment")' k8s-resources.yaml

# Combine YAML files
yq eval-all '. as $item ireduce ({}; . * $item)' file1.yaml file2.yaml

对象操作

# Get all keys
yq 'keys' file.yaml

# Select specific fields
yq '{name, version}' file.yaml

# Merge objects
yq '. * {"updated": true}' file.yaml
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml

# Deep merge
yq eval-all '. as $item ireduce ({}; . *+ $item)' base.yaml override.yaml

JSON 输出（用于管道传递）

# YAML to JSON
yq -o=json '.' file.yaml

# Compact single-line JSON — the form to pipe into jq or a tool that reads stdin
yq -o=json -I=0 '.' file.yaml

快速参考

运算符

• .field - 访问字段
• .[] - 遍历数组/对象
• | - 管道（链式操作）
• , - 多个输出
• // - 备选运算符（默认值）
• * - 合并对象（浅层）
• *+ - 深度合并对象

函数

• keys、values - 对象的键/值
• length - 数组/对象/字符串长度
• select() - 筛选
• sort_by() - 排序
• group_by() - 分组
• unique - 删除重复项
• has() - 检查字段是否存在
• type - 获取值类型
• add - 求和或拼接
• del() - 删除字段

标志

标志	描述
-i	就地编辑
-o	输出格式（json、yaml、xml、csv、tsv、props）
-p	输入格式（json、yaml、xml）
-I	缩进（默认值：2）
-r	原始输出（不带引号）
-n	空输入（从头创建）
-s	拆分多文档 YAML

字符串函数

• split()、join() - 字符串/数组转换
• contains() - 检查字符串/数组是否包含指定内容
• test() - 正则表达式匹配
• sub()、gsub() - 字符串替换
• upcase、downcase - 大小写转换

详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。

资源

• 官方文档：https://mikefarah.gitbook.io/yq/
• GitHub 仓库：https://github.com/mikefarah/yq
• 使用 Docker 试用：docker run --rm -i mikefarah/yq '.key' <<< 'key: value'
• 运算符参考：https://mikefarah.gitbook.io/yq/operators/