yq命令参考大全：最完整的操作语法手册
项目地址: https://gitcode.com/GitHub_Trending/yq/yq 引言：告别YAML处理痛点
你是否还在为复杂YAML文件的解析和修改而烦恼？作为DevOps工程师、开发者或数据分析师，处理YAML/JSON/XML等数据格式时，你可能经常需要：
- 从多层嵌套结构中快速提取关键信息
- 批量修改配置文件中的特定字段
- 合并多个配置文件并解决冲突
- 对数组和对象进行复杂过滤和转换
yq（YAML Query）作为一款轻量级命令行工具，正是为解决这些痛点而生。它采用类jq语法，支持YAML、JSON、XML、CSV等多种格式，提供了强大的数据查询、修改和转换能力。本文将系统梳理yq的核心操作语法，通过100+实战示例，帮助你掌握从基础到高级的全部技能。
读完本文后，你将能够：
- 熟练使用30+核心操作符处理各类数据结构
- 掌握复杂场景下的表达式组合技巧
- 高效完成配置文件管理、数据清洗和格式转换任务
- 理解yq与jq的差异及迁移策略
快速入门：安装与基础语法
安装指南
yq提供多平台二进制文件和包管理器安装方式，国内用户推荐以下方法：
# Linux (AMD64)
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq
# macOS (Homebrew)
brew install yq
# Windows (Chocolatey)
choco install yq
验证安装：
yq --version # 应输出 v4.x.x
核心语法框架
yq遵循"表达式-文件"的基本使用模式，核心语法结构如下：
# 基本语法
yq [选项] '<表达式>' [文件...]
# 常用选项
-i, --inplace # 原地修改文件
-n, --null-input # 不读取输入，直接执行表达式
-p, --input-format # 指定输入格式(auto/yaml/json/xml/csv)
-o, --output-format # 指定输出格式
-e, --exit-status # 根据结果设置退出状态码
数据选择基础
| 表达式 | 功能描述 | 示例 |
|---|---|---|
. | 选择根节点 | yq '.' file.yaml |
.key | 选择键为key的子节点 | yq '.name' config.yaml |
.[index] | 选择数组指定索引元素 | yq '.items[0]' list.yaml |
.[start:end] | 数组切片 | yq '.items[1:3]' list.yaml |
.. | 递归遍历所有节点 | yq '.. | .name' deep.yaml |
示例：读取多层嵌套数据
给定sample.yaml：
a:
b:
- name: "Alice"
age: 30
- name: "Bob"
age: 25
# 提取第二个用户的年龄
yq '.a.b[1].age' sample.yaml # 输出: 25
# 递归提取所有name字段
yq '.. | .name' sample.yaml # 输出: Alice \n Bob
核心操作符全解析
1. 数据选择与过滤
select：条件筛选
语法：.[] | select(<条件表达式>)
示例：筛选数组元素
# 筛选age>28的用户
yq '.a.b[] | select(.age > 28)' sample.yaml
输出：
name: "Alice"
age: 30
高级用法：多条件组合
# 筛选age>25且name包含"li"的用户
yq '.a.b[] | select(.age > 25 and .name | contains("li"))' sample.yaml
contains：包含判断
语法：contains(<值>)
示例：判断数组包含关系
# 检查数组是否包含特定元素
yq '.tags | contains(["prod", "web"])' config.yaml
字符串包含检查：
# 检查name字段是否包含"Ali"
yq '.a.b[0].name | contains("Ali")' sample.yaml # 输出: true
2. 数据修改与更新
= / |=：赋值操作符
语法：<路径> = <值> 或 <路径> |= <表达式>
示例：基本赋值
# 原地更新文件中的版本号
yq -i '.version = "1.0.1"' config.yaml
示例：基于原 value 更新
# 将所有age增加5
yq '.a.b[].age |= . + 5' sample.yaml
add：元素添加
语法：<数组> + <值> 或 <数组> += <值>
示例：数组拼接
# 合并两个数组
yq '.a + .b' data.yaml
示例：追加元素
# 向数组追加新元素
yq '.items += "new-item"' list.yaml
del：删除操作
语法：del(<路径>)
示例：删除指定节点
# 删除第二个用户
yq 'del(.a.b[1])' sample.yaml
示例：条件删除
# 删除age<28的用户
yq 'del(.a.b[] | select(.age < 28))' sample.yaml
3. 逻辑与比较运算
布尔运算符
支持and、or、not逻辑运算，以及==、!=、>、<等比较运算符。
示例：多条件筛选
# 选择age在25-35之间的用户
yq '.a.b[] | select(.age >= 25 and .age <= 35)' sample.yaml
any / all：数组逻辑判断
语法：any（任一元素满足）、all（所有元素满足）
示例：检查数组条件
# 判断是否有用户年龄大于30
yq '.a.b[].age | any(. > 30)' sample.yaml
4. 数据转换与计算
keys：获取键列表
语法：keys
示例：获取对象所有键
# 获取用户对象的所有属性名
yq '.a.b[0] | keys' sample.yaml
输出：
- name
- age
length：长度计算
语法：length
示例：计算数组长度
# 获取用户数量
yq '.a.b | length' sample.yaml # 输出: 2
sort / sort_by：排序
语法：sort（基本排序）、sort_by(<表达式>)（按指定条件排序）
示例：按年龄排序用户
# 按age升序排列
yq '.a.b | sort_by(.age)' sample.yaml
示例：降序排列
# 按age降序排列
yq '.a.b | sort_by(.age) | reverse' sample.yaml
高级应用场景
1. 文件合并与处理
多文件合并
# 合并两个YAML文件（后者覆盖前者）
yq eval-all 'select(fileIndex==0) * select(fileIndex==1)' base.yaml override.yaml
批量处理多个文件
# 为所有YAML文件添加环境标记
yq -i '.env = "prod"' configs/*.yaml
2. 格式转换
JSON与YAML互转
# JSON转YAML
yq -Poy input.json > output.yaml
# YAML转JSON
yq -oj input.yaml > output.json
CSV转换
# CSV转YAML数组
yq --input-format csv '.' data.csv
3. 复杂数据处理流程
示例：数据提取与转换流水线
# 从JSON日志中提取错误信息并格式化
cat app.log | yq -p json '.[] | select(.level == "error") | {time: .timestamp, msg: .message}'
流程图：yq数据处理流水线
实战技巧与最佳实践
常用命令速查表
| 任务 | 命令示例 |
|---|---|
| 读取特定字段 | yq '.key.subkey' file.yaml |
| 条件更新 | yq '.key[] |= select(condition).field = value' file.yaml |
| 文件合并 | yq eval-all '. as $item ireduce({}; . * $item)' *.yaml |
| 环境变量注入 | NAME=mike yq '.name = strenv(NAME)' file.yaml |
| 注释保留 | yq -i '.key = "value"' file.yaml（自动保留注释） |
性能优化建议
- 避免深层递归：
..操作符可能导致性能问题，尽量使用明确路径 - 流式处理大文件：使用
eval-all替代多次调用 - 批量操作：利用通配符一次性处理多个文件
常见问题解决
Q: 如何处理包含特殊字符的键名？
A: 使用引号包裹键名：yq '."my-key.with.dots"' file.yaml
Q: 如何保留原文件格式和注释？
A: 使用-i选项原地修改，yq会自动保留注释和样式
总结与展望
yq作为一款功能强大的命令行数据处理工具，凭借其类jq语法和多格式支持，已成为YAML/JSON处理的得力助手。本文系统介绍了其核心操作符、高级应用和实战技巧，涵盖了从基础查询到复杂转换的全场景需求。
随着数据处理需求的不断增长，yq也在持续进化。未来版本可能会增强对复杂数据结构的支持，并优化大型文件处理性能。掌握yq不仅能显著提升配置管理效率，更能为DevOps自动化、数据清洗等场景提供强大助力。
立即行动：使用yq --help探索更多选项，或访问官方文档获取最新教程。如有疑问，欢迎在项目GitHub仓库提交issue或参与讨论。
本文基于yq v4.x版本编写，部分功能可能随版本更新有所变化，请以官方文档为准。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
