GeekIt

yq命令速查

安装与读取、取值过滤、修改与原地编辑、格式互转、多文件合并、K8s/Helm 实战、注释锚点与报错排查等 164 条命令

共 164 条命令 · 11 类场景 · 点击右侧图标可复制

命令 / 片段说明复制
yq --version确认是 mikefarah/yq v4;v3 与 v4 语法完全不同
yq -h查看全部参数,v4 参数以它为准
brew install yqmacOS 安装
apt install yqDebian/Ubuntu,注意部分源提供的仍是旧版
snap install yqsnap 安装,版本通常较新
go install github.com/mikefarah/yq/v4@latestGo 安装,可精确控制版本
yq '.' file.yaml格式化输出,最常用的入门命令
yq eval '.' file.yamleval 是默认子命令,写全与省略等价
yq --help查看全局参数与子命令列表
yq completion bash > /etc/bash_completion.d/yq开启 shell 补全,长表达式更省心
yq v3 与 v4 不兼容老教程里的 yq read / yq write 在 v4 已不存在
命令 / 片段说明复制
yq '.a' file.yaml取顶层字段,直接输出 YAML 片段
yq '.a.b.c' file.yaml链式取嵌套字段
yq -P '.' file.yaml美化打印,长行折行更易读
yq -I 4 '.' file.yaml指定缩进为 4 空格
yq -I 0 '.' file.yaml不缩进,配合 -o=json 得到紧凑 JSON
yq -N '.' file.yaml输出不打印 --- 文档分隔符
yq -e '.a == "x"' file.yaml结果为 false 时退出码非 0,做条件判断
yq -r '.a' file.yaml去掉字符串引号输出,赋值给 shell 变量时用
yq -M '.' file.yaml关闭彩色输出,写文件或进日志时用
yq -C '.' file.yaml强制彩色,管道给 less -R 时用
yq -0 '.items[].name' file.yaml用 NUL 分隔输出,适配 xargs -0
yq '.a' file.yaml | less -R大文件分页查看
yq -o=json '.' file.yamlYAML 直接转 JSON
yq -o=props '.' file.yaml输出 Java properties 格式
yq -o=xml '.' file.yaml输出 XML,兼容部分老系统
yq '.' file.yaml > out.yaml重定向保存,先不加 -i 更安全
yq '.' - < file.yaml从标准输入读取,管道场景用
命令 / 片段说明复制
yq '.items[0]' file.yaml取数组第一个元素
yq '.items[-1]' file.yaml取最后一个元素
yq '.items[]' file.yaml展开数组,逐个输出文档
yq '.items[].name' file.yaml展开后取字段
yq '.items[]?.name' file.yaml元素为空时跳过,避免报错
yq '.["foo-bar"]' file.yaml键名含特殊字符时用方括号写法
yq '.. | select(has("name")) | .name' file.yaml递归查找所有 name 字段
yq 'select(.kind == "Deployment")' file.yaml按条件过滤文档
yq '.items[] | select(.enabled == true)' file.yaml过滤数组元素
yq '.items[] | select(.name | test("^web"))' file.yaml正则匹配过滤
yq '.a // "default"' file.yaml为空时给默认值
yq '[.items[].name]' file.yaml收集成数组输出
yq '.items | length' file.yaml取数组或对象长度
yq '.a | keys' file.yaml列出键名
yq '.a | has("b")' file.yaml判断字段是否存在
yq '.a | type' file.yaml查看值的 YAML 类型
yq '.a | tag' file.yaml查看 YAML 标签,如 !!str、!!int
yq 'to_entries' file.yaml对象转 key/value 数组
yq 'with_entries(select(.key != "tmp"))' file.yaml按 key 过滤字段
yq '.items | sort_by(.name)' file.yaml按字段排序
yq '.items | group_by(.type)' file.yaml按字段分组
yq '.items | unique_by(.id)' file.yaml按字段去重
yq '.items | map(.name)' file.yaml投影出字段数组
yq '.items[] | .name + ":" + .port' file.yaml字符串拼接输出
命令 / 片段说明复制
yq '.a = "x"' file.yaml赋值,字段不存在则新建
yq '.a.b.c = 1' file.yaml逐层创建嵌套字段
yq '.a |= . + 1' file.yaml基于旧值更新
yq '.a += "suffix"' file.yaml追加字符串
yq '.list += ["new"]' file.yaml数组追加元素
yq 'del(.a)' file.yaml删除字段
yq 'del(.items[].secret)' file.yaml批量删除数组元素里的字段
yq '.items[0].name = "x"' file.yaml按下标修改
yq '.items |= map(select(.id != 2))' file.yaml过滤掉指定元素
yq '.a as $v | .b = $v' file.yaml用变量复用同一个值
yq 'with(.a; .b = 1 | .c = 2)' file.yaml对子节点批量操作,避免重复写路径
yq -i '.a = 1' file.yaml原地修改文件,最常用的编辑方式
yq -i '.spec.replicas = 3' deploy.yaml改副本数,改完直接 kubectl apply
cp file.yaml file.yaml.bak && yq -i '.a = 1' file.yaml原地改之前先备份,避免手误
yq -i -o=json '.' config.yaml把 YAML 文件原地换成 JSON 内容
yq -i '.a = strenv(MY_VAR)' file.yaml把环境变量写进去,自动处理类型与转义
yq -i '.a = env(MY_VAR)' file.yaml与 strenv 类似,需注意值与解析方式
命令 / 片段说明复制
yq -o=json '.' file.yamlYAML 转 JSON,配合 jq 做复杂处理
yq -o=json -I=0 '.' file.yaml输出紧凑单行 JSON
yq -p=json -o=yaml '.' file.jsonJSON 转 YAML,迁移配置常用
yq -p=json '.a.b' data.json不转换格式直接按 JSON 读取取值
yq -p=yaml -o=csv '.items[]' file.yaml转 CSV,适合导出表格
yq -p=yaml -o=tsv '.items[]' file.yaml转 TSV,贴进 Excel 更稳
yq -o=json '.' file.yaml | jq '.items[].name'yq 负责解析 YAML,jq 负责复杂查询
yq -p=xml -o=yaml '.' config.xmlXML 转 YAML
yq -p=csv -o=yaml '.' data.csvCSV 转 YAML
yq -o=props '.' file.yamlYAML 转 properties
kubectl get deploy -o yaml | yq -o=json '.'管道里即时转换,便于程序处理
yq '.' file.yaml > file.ymlyaml 与 yml 后缀只是习惯差异
转换后先 diff 再覆盖格式转换会丢失注释与锚点,谨慎用于生产配置
命令 / 片段说明复制
yq '.a' a.yaml b.yaml多个文件依次处理,输出各自结果
yq ea '.' a.yaml b.yamleval-all 把所有文件当作一个流处理
yq ea '. as $item ireduce ({}; . * $item)' a.yaml b.yaml多文件深度合并,覆盖式配置最常用
yq ea 'select(fileIndex == 0) * select(fileIndex == 1)' a.yaml b.yaml按文件下标合并,逻辑更清晰
yq ea '[.] | add' a.yaml b.yaml数组形式合并所有文档
yq -s '.metadata.name' file.yaml按表达式结果拆分成多个文件输出
yq '.' multi.yaml多文档 YAML 会自动按 --- 分隔输出
yq 'select(.kind == "Service")' all.yaml从多文档中筛出指定类型资源
yq 'fileIndex' a.yaml b.yaml查看当前文档来自第几个文件
yq 'documentIndex' all.yaml查看当前是文件内第几个文档
yq '.' *.yaml > merged.yaml简单拼接,注意会产生多文档而不是合并
合并前确认同名键的覆盖顺序ireduce 里后者覆盖前者,顺序写反会得到意外结果
命令 / 片段说明复制
yq '.spec.template.spec.containers[].image' deploy.yaml取所有容器镜像,做版本审计
yq '.metadata.labels.env = "prod"' -i deploy.yaml给资源加标签
yq '.spec.replicas = 5' -i deploy.yaml调整副本数
yq '.spec.template.spec.containers[0].resources.limits.cpu = "1"' -i deploy.yaml改资源限制,注意字符串引号不能丢
yq 'select(.kind == "Deployment") | .metadata.name' all.yaml从清单中筛出 Deployment 名
yq -o=json '.' deploy.yaml | jq '.spec.template.spec.containers[].env'环境变量审计,jq 处理数组更顺手
yq '.spec.template.spec.containers[].env[] | select(.name == "TZ")' deploy.yaml定位指定环境变量
yq '.image.tag = "v1.2.3"' -i values.yaml改 Helm values 里的镜像版本
yq '.resources.limits.memory = "512Mi"' -i values.yaml改 Helm 资源限制
yq ea '. as $v | load("base.yaml") * $v' values.yaml基础配置叠加环境覆盖(load 读取其他文件)
helm template app ./chart | yq '.kind'渲染后先看资源类型清单
helm values app -a | yq '.app.image'查看生效的 values
yq 'del(.metadata.creationTimestamp, .status)' -i dump.yaml清理运行时字段后再入库或对比
压平多文档再比对用 yq -o=json 后 diff,比直接 diff yaml 更准
命令 / 片段说明复制
yq '... comments=""' file.yaml清空所有注释,生成干净的交付文件
yq '.a line_comment="说明"' file.yaml在字段右侧写行内注释
yq '.a head_comment="说明"' file.yaml在字段上方写注释
yq '.a | . style="double"' file.yaml控制字符串引号风格:double/single/literal/folded
yq '.a style="flow"' file.yaml数组或对象用流式写法,压缩行数
yq 'explode(.)' file.yaml展开锚点与别名,输出无 & 与 * 的等价内容
yq '.a = .b' file.yaml赋值时可能引入锚点复用,需要时用 explode 拆开
yq '.[] | anchor' file.yaml查看节点上的锚点名称
yq '.a alias = "x"' file.yaml创建别名引用已有锚点
yq '.a | .[0] style="flow"' file.yaml只对某个子节点改风格
yq -P '.' file.yaml美化后注释与空行更规整,便于人工 review
注释在格式转换后会丢失YAML 转 JSON 再转回来,注释与锚点都无法保留
yq -i 会保留未修改部分的注释原地编辑比全量重写更安全
命令 / 片段说明复制
yq -n '{a: 1}'不读输入,直接构造 YAML
yq -n --arg name zs '{user: $name}'注入字符串参数
yq -n '{user: strenv(USER), ts: now}'拼接环境变量与时间戳
yq '.a = strenv(V)' -i file.yamlCI 中动态写入版本号或镜像 tag
yq -e '.a.b == "x"' file.yaml条件断言,失败退出码非 0
yq '.a' file.yaml || echo "字段不存在"配合 -e 做存在性校验
yq -r '.a' file.yaml | xargs -I{} echo {}输出裸字符串交给 shell 处理
yq -0 '.items[].name' file.yaml | xargs -0 -n1 echo名称含空格时用 NUL 分隔
for f in *.yaml; do yq -i '.metadata.labels.team = "ops"' "$f"; done批量改目录下所有清单
yq '.a' file.yaml > tmp && mv tmp file.yaml不用 -i 的手动替换方式,便于失败回滚
yq -e '.kind' file.yaml > /dev/null || exit 1校验文件是否是合法 K8s 清单
表达式用单引号包裹避免 shell 提前解析 $ 与反引号
复杂逻辑写入脚本文件再调用命令行过长易出错,维护成本也高
yq 与 jq 组合使用yq 解析 YAML,jq 做复杂 JSON 计算
命令 / 片段说明复制
jq 只处理 JSONyq 原生支持 YAML/JSON/XML/CSV/props 多种格式
yq 语法不是 jq 的子集select/map 等相似,但 path 与操作符存在差异
yq '.a' vs jq '.a'简单取值写法一致,可以互相对照记忆
yq 支持 -i 原地编辑jq 需要重定向加 mv 才能改文件
jq 的 @csv 在 yq 里用 -o=csv输出格式通过参数控制,而不是过滤器
yq 会保留注释与锚点这是它比 YAML 转 JSON 再转回来更适合改配置的关键原因
yq -o=json | jq混合使用的标准姿势:各取所长
yq 的 ea 对应 jq 的 -s都是把多个输入合并成一个流处理
yq 的 strenv 对应 jq 的 --arg都能安全注入外部变量
复杂聚合仍建议交给 jqyq 在数组统计与正则上功能较少
命令 / 片段说明复制
Error: bad expression, could not find matching表达式语法错误,多为引号或括号不配对
Error: cannot index array with "x"对数组用字段取值,应先 .[] 或加下标
Error: cannot index map with 0对对象用下标,改成字段名取值
Error: failed to read file路径错误或无读权限
yq read: command not found照着 v3 教程抄的,v4 已移除该子命令
-i 必须指定文件原地编辑不支持标准输入,需给文件名
yaml: line N: did not find expected key源文件缩进或冒号写错,先修复 YAML 本身
yaml: mapping values are not allowed here值里有冒号或特殊字符却没加引号
JSON 文件报 YAML 解析错误用 -p=json 指定输入格式
unknown flag: --xxx参数属于旧版本,用 yq -h 核对
-e 时脚本退出表达式结果为 false 或 null,检查条件是否正确
输出里出现 !!timestamp 等标签YAML 特殊类型,转为 JSON 前确认下游能否处理
多文档输出混在一起用 select(fileIndex == N) 或 -s 拆分
中文变成转义序列被转成 JSON 时常见,用 -o=yaml 或加 -r 处理
修改后缩进被重排yq 会按自身规则重排格式,改前先备份再 diff
注释丢失全量转换或管道重写会丢注释,敏感文件改用 -i 局部修改
锚点被展开管道或格式转换会展开引用,需要保留就避免全量重写
Windows 下引号被吃掉PowerShell 对单引号处理不同,改用双引号并转义
容器里 yq 版本不对镜像自带的是 v3 或 Python 版 yq,锁版本或换官方镜像

运维常用组合

改镜像版本yq '.spec.template.spec.containers[].image = "registry/app:v1.2.3"' -i deploy.yaml && kubectl apply -f deploy.yaml
批量打标签for f in k8s/*.yaml; do yq -i '.metadata.labels.team = "ops"' "$f"; done
YAML 转 JSON 给程序yq -o=json -I=0 '.' config.yaml > config.json
多环境配置合并yq ea '. as $item ireduce ({}; . * $item)' base.yaml prod.yaml > final.yaml
导出资源清单kubectl get deploy -n prod -o yaml | yq -o=json '.' | jq -r '.items[] | [.metadata.name, .spec.replicas] | @tsv'
流水线校验yq -e '.image.tag != null' values.yaml && echo pass || echo "缺少 image.tag"

实战要点

1. 确认是 v4

网上大量教程是 v3 语法,先看 yq --version,避免照抄不兼容命令

2. 改文件先备份

-i 是原地写入,出错会直接破坏配置,改前 cp 一份或用 git 兜底

3. yq 转 jq 处理

YAML 交给 yq 解析、复杂统计交给 jq,是最高效的组合

4. 注释与锚点会丢

格式转换与全量重写都会丢失注释,配置文件尽量用 -i 局部修改

5. 注入变量用 strenv

别用字符串拼接,strenv 会自动处理引号与转义

6. 多环境用 ea 合并

base 与覆盖文件按 ireduce 深度合并,注意后者覆盖前者的顺序

共 164 条 yq 命令 · 示例中的文件路径与字段名请替换为实际环境

关于yq命令速查

在线 yq(mikefarah/yq v4)命令速查手册,按安装与版本、基础读取、取值与过滤、修改与原地编辑、格式互转、多文件与多文档、K8s 与 Helm 实战、注释锚点与样式、参数与脚本化、与 jq 对比、常见报错与排查等 11 类场景整理 160 余条常用命令与表达式,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 yq --version 与 brew/apt/snap/go install 与 yq -h、yq '.' file.yaml 格式化与 -P 美化 与 -I 缩进 与 -N 去掉文档分隔符 与 -e 退出码 与 -M/-C 颜色 与 -r 去引号 与 -0 NUL 分隔 与 --front-matter、yq -o=json 与 -o=yaml 与 -o=props 与 -o=csv 与 -o=tsv 与 -o=xml 与 -p=json/-p=xml/-p=csv 指定输入格式 与 -I=0 紧凑 JSON、.a.b 与 .a[0] 与 .a[] 与 .["key"] 与 .a[]?.b 容错 与 select() 与 map() 与 to_entries/with_entries 与 sort_by/group_by/unique_by 与 keys/length/has 与 .. 递归 与 path/getpath 与 type/tag、.a = "x" 与 .a |= . + 1 与 .a += 1 与 del(.a) 与 with(.a; .b=1) 与 -i 原地修改 与 strenv()/env() 注入变量 与 explode(.) 展开锚点 与 ... comments="" 清理注释 与 .a line_comment/head_comment 写注释 与 style="double" 控制引号风格、yq ea 多文件合并 与 ireduce 深度合并 与 -s 按表达式拆分输出文件 与 多文档 --- 处理,以及 .spec.template.spec.containers[].image 取镜像 与 .spec.replicas = 5 改副本 与 .metadata.labels.env = "prod" 加标签 与 select(.kind == "Deployment") 筛资源 与 helm values 覆盖,还有 bad expression、cannot index array with、failed to read file、v3 的 yq read/yq w 在 v4 不存在、-i 必须给文件、YAML 缩进解析错误、-e 退出码非 0、JSON 输入忘加 -p=json、unknown flag 等报错排查。适用于 Kubernetes 与 Helm 清单批量修改、CI 中动态生成配置、YAML 与 JSON/CSV 互转、配置文件字段提取与审计、多环境 values 合并,以及运维、SRE 与平台工程师面试复习。

核心能力

  • 涵盖 yq --version 与 brew/apt/snap/go install 与 yq -h、yq '.' file.yaml 格式化与 -P 美化 与 -I 缩进 与 -N 去掉文档分隔符 与 -e 退出码 与 -M/-C 颜色 与 -r 去引号 与 -0 NUL 分隔 与 --front-matter、yq -o=json 与 -o=yaml 与 -o=props 与 -o=csv 与 -o=tsv 与 -o=xml 与 -p=json/-p=xml/-p=csv 指定输入格式 与 -I=0 紧凑 JSON、.a.b 与 .a[0] 与 .a[] 与 .["key"] 与 .a[]?.b 容错 与 select() 与 map() 与 to_entries/with_entries 与 sort_by/group_by/unique_by 与 keys/length/has 与 .. 递归 与 path/getpath 与 type/tag、.a = "x" 与 .a |= . + 1 与 .a += 1 与 del(.a) 与 with(.a
  • .b=1) 与 -i 原地修改 与 strenv()/env() 注入变量 与 explode(.) 展开锚点 与 ... comments="" 清理注释 与 .a line_comment/head_comment 写注释 与 style="double" 控制引号风格、yq ea 多文件合并 与 ireduce 深度合并 与 -s 按表达式拆分输出文件 与 多文档 --- 处理,以及 .spec.template.spec.containers[].image 取镜像 与 .spec.replicas = 5 改副本 与 .metadata.labels.env = "prod" 加标签 与 select(.kind == "Deployment") 筛资源 与 helm values 覆盖,还有 bad expression、cannot index array with、failed to read file、v3 的 yq read/yq w 在 v4 不存在、-i 必须给文件、YAML 缩进解析错误、-e 退出码非 0、JSON 输入忘加 -p=json、unknown flag 等报错排查

适用场景

适用于 Kubernetes 与 Helm 清单批量修改、CI 中动态生成配置、YAML 与 JSON/CSV 互转、配置文件字段提取与审计、多环境 values 合并,以及运维、SRE 与平台工程师面试复习。yq命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

yq命令速查是免费的吗?需要注册或安装吗?
yq命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
yq命令速查支持哪些功能?
涵盖 yq --version 与 brew/apt/snap/go install 与 yq -h、yq '.' file.yaml 格式化与 -P 美化 与 -I 缩进 与 -N 去掉文档分隔符 与 -e 退出码 与 -M/-C 颜色 与 -r 去引号 与 -0 NUL 分隔 与 --front-matter、yq -o=json 与 -o=yaml 与 -o=props 与 -o=csv 与 -o=tsv 与 -o=xml 与 -p=json/-p=xml/-p=csv 指定输入格式 与 -I=0 紧凑 JSON、.a.b 与 .a[0] 与 .a[] 与 .["key"] 与 .a[]?.b 容错 与 select() 与 map() 与 to_entries/with_entries 与 sort_by/group_by/unique_by 与 keys/length/has 与 .. 递归 与 path/getpath 与 type/tag、.a = "x" 与 .a |= . + 1 与 .a += 1 与 del(.a) 与 with(.a;.b=1) 与 -i 原地修改 与 strenv()/env() 注入变量 与 explode(.) 展开锚点 与 ... comments="" 清理注释 与 .a line_comment/head_comment 写注释 与 style="double" 控制引号风格、yq ea 多文件合并 与 ireduce 深度合并 与 -s 按表达式拆分输出文件 与 多文档 --- 处理,以及 .spec.template.spec.containers[].image 取镜像 与 .spec.replicas = 5 改副本 与 .metadata.labels.env = "prod" 加标签 与 select(.kind == "Deployment") 筛资源 与 helm values 覆盖,还有 bad expression、cannot index array with、failed to read file、v3 的 yq read/yq w 在 v4 不存在、-i 必须给文件、YAML 缩进解析错误、-e 退出码非 0、JSON 输入忘加 -p=json、unknown flag 等报错排查。
yq命令速查适合哪些场景使用?
适用于 Kubernetes 与 Helm 清单批量修改、CI 中动态生成配置、YAML 与 JSON/CSV 互转、配置文件字段提取与审计、多环境 values 合并,以及运维、SRE 与平台工程师面试复习。