jq命令详解API 调试、CI 日志、Kuberneteskubectl输出、配置文件巡检——碰到 JSON 时grep容易误伤引号与嵌套jq用声明式过滤器直接查询、裁剪、重组 JSON是命令行下的标配工具。速览语法jq 过滤器 file.json或cat file.json | jq 过滤器取字段.name、.address.city数组.items[0]、.items[]过滤select(.age 20)构造{user: .name}常用选项-r去引号、-c压缩一行、-s多行 JSON 合并为数组表达式必须加引号jq .name✅jq .name❌shell 会拆参数核心结论30 秒版只看结构→jq .或jq -C .彩色格式化。提一个字段给脚本→jq -r .name。筛数组→.items[] | select(.status ok)。改字段不改文件→jq .age 1输出到新文件或管道。JSON 用jq纯文本行用grep别用 grep 解析 JSON。速查卡片jq . 格式化 jq -r .name 取字段无引号给 shell jq .items[] 展开数组 jq .items[] | select(.ok) 筛数组元素 jq select(.age 20) 筛根对象单条 JSON jq {a: .name, b: .city} 构造对象 jq .items | map(.name) 批量变换 jq -c ... 一行一条JSON Lines jq -e ... 失败时 exit 1脚本判断目录1. 安装与调用2. 示例数据3. 基础用法取值与遍历4. 过滤 select5. 构造与变换6. 常用内置函数7. 常用选项8. 实战场景9. jq、grep 与 yq10. 常见坑11. 何时不必用 jq12. 延伸阅读1. 安装与调用平台安装Linuxapt install jq/dnf install jqmacOSbrew install jqWindowswinget install jqlang.jq或 WSLjq[选项]jq表达式文件.jsoncat文件.json|jqjq表达式curl-sURL|jqjq表达式JSON 输入文件 / 管道 / curljq 过滤器格式化 / 字段 / 新 JSON2. 示例数据下文示例统一使用data.json{name:Alice,age:25,skills:[jq,bash,python],address:{city:Beijing,zip:100000}}数组场景补充users.json{items:[{name:Alice,age:25,status:ok},{name:Bob,age:17,status:ok},{name:Carol,age:30,status:fail}]}3. 基础用法取值与遍历3.1 格式化与类型命令作用jq . data.json美化缩进最常用jq -C . data.json彩色输出TTY 下jq type data.json根节点类型 →object3.2 对象字段与数组下标jq.namedata.json# Alicejq.address.citydata.json# Beijingjq-r.namedata.json# Alice -r 去掉 JSON 引号适合 shell 变量jq.skills[0]data.json# jqjq.skills[-1]data.json# pythonjq.skills | lengthdata.json# 3字段可能不存在时用//默认值jq.phone // N/Adata.json# N/A3.3 展开数组与管道jq.skills[]data.jsonjq bash python对象键值jqkeysdata.json# [address, age, name, skills]jqto_entries[] | .keydata.json# name age skills address 多行输出管道|左侧输出作为右侧输入。jq.skills | map(ascii_upcase)data.json# [JQ, BASH, PYTHON]4. 过滤 select区分两种写法对数组元素过滤前要先[]展开select作用在单个元素上对根对象整条 JSON 就是一个 object可直接select(条件)保留或丢弃整份输入。4.1 数组元素过滤jq.skills[] | select(. bash)data.json# bashjq.items[] | select(.status ok)users.json第二条输出两行对象Alice、Bob。若写成jq .items | select(.status ok)则错误——此时.是整个数组不是元素。4.2 根对象过滤单对象 JSONjqselect(.age 20)data.json年龄 ≤ 20 时 jq 无输出该条被丢弃。4.3 多条件jqselect(.age 20 and .name Alice)data.json jq.items[] | select(.age 18 and .status ok)users.json# 仅 Alice5. 构造与变换5.1 生成新对象jq{user: .name, location: .address.city}data.json{user:Alice,location:Beijing}5.2 修改字段不可变风格jq.age 1data.json jq.skills [go]data.json jqdel(.address.zip)data.json输出为新 JSON原文件不变写回需重定向jq ... data.json data.new.json或jq ... file | sponge filemoreutils。5.3 map 批量变换jq.items | map({name, adult: (.age 18)})users.json[{name:Alice,adult:true},{name:Bob,adult:false},{name:Carol,adult:true}]6. 常用内置函数函数说明示例length字符串/数组长度.skills | length→3keys对象键数组keyshas(key)是否含键has(name)→truemap(f)数组映射map(.name)join(sep)数组拼字符串.skills | join(, )sort/sort_by(.field)排序.items | sort_by(.age)unique去重uniquegroup_by(.field)分组.items | group_by(.status)jq.skills | join(, )data.json# jq, bash, pythonjq.items | group_by(.status)users.json# [{status:fail,...}, {status:ok,...}] 两组7. 常用选项选项作用-rraw 输出字符串无引号-ccompact一行一条 JSON流式处理友好-sslurp多行/多个 JSON 文档读入为数组-C彩色-e过滤器结果为 false/null 时 exit 1脚本判断--arg k v传入外部变量$k--argjson k v传入 JSON 变量--stream流式解析超大 JSON进阶见下# slurp多个 JSON 文件合并为一个数组jq-s.a.json b.json# 外部变量jq--argprefixuser{id: ($prefix _ .name)}data.json# {id: user_Alice}--stream进阶日常 API /kubectl响应无需--stream。仅当单文件数百 MB、无法一次jq .载入时考虑# 流式输出 [路径, 值] 对路径末级为叶子时 length2jq--streamselect(length 2)huge.json|head语义较难详见 jq 手册 --stream多数场景用jq -c处理 JSON Lines 即可。8. 实战场景8.1 API 提取字段curl-shttps://api.github.com/users/octocat\|jq{login, id, public_repos}8.2 Kuberneteskubectl get pods-ojson\|jq.items[] | select(.status.phase ! Running) | .metadata.namekubectl get pod my-pod-ojson\|jq-r.spec.containers[].imageYAML 清单常用兄弟工具yq见 §9。8.3 统计与聚合jq.items | lengthusers.json# 3jq[.items[].age] | add / lengthusers.json# 24平均年龄jq[.items[] | select(.statusfail)] | lengthusers.json# 18.4 CI / 日志一行 JSONgrep^{app.log|jq-cselect(.level ERROR) | {ts, msg}CI 脚本建议开头set-euopipefail# ...if!jq-e.build.passed truereport.json/dev/null;thenechobuild failed2;exit1fi避免jq解析失败或-e判假时被管道静默吞掉。8.5 与 shell 变量name$(jq-r.namedata.json)ifjq-e.age 18data.json/dev/null;thenechoadult;fi9. jq、grep 与 yq场景工具结构化 JSON 取字段、改结构jqYAMLK8s manifest、docker-composeyq语法与 jq 高度相似如yq .spec.replicas deploy.yaml纯文本日志、非 JSON 行grep/rgJSON 里搜子串应急jq -r .. | strings | grep foo笨重错误curl ... | grep name # 易匹配错字段、无法处理嵌套 正确curl ... | jq -r .nameJSON Lines每行一个 JSON常用jq -c或逐行管道。10. 常见坑坑正确做法jq .name无引号shell 拆词 →jq .name输出带引号无法赋变量字符串用-r对数组select忘写[].items[] | select(...)修改原文件jq 只 stdout →重定向或spongenull字段//默认值或select(has(x))数字与字符串比较.id 123vs.id 123类型要一致CI 中 jq 失败被忽略set -euo pipefail-e11. 何时不必用 jq场景更合适的工具GB 级 JSON ETL、复杂多步关联Python / Go / DuckDBjq 全量读入慢复杂业务逻辑、多文件事务应用代码而非 shell 一行链原地改文件jq 不直接写盘需重定向或sponge易误覆盖非 JSON纯文本、CSV 主场景awk/csvkit/ 专用解析器YAML 为主yq或kubectl内置-o json再 jqjq 的定位是命令行上的 JSON 瑞士军刀——快、声明式、管道友好不是通用数据处理平台。12. 延伸阅读资源说明jq 官网手册与教程jq 手册 jq(1)内置函数全集jq play浏览器试过滤器yqYAML 处理jq 语法子集复杂过滤器可先在 jq play 验证再写入脚本生产脚本对-e与exit code做好判断避免静默失败。收束jq 把 JSON 当成有类型的数据结构来切而不是文本行记住引号包表达式、-r给 shell、数组先[]再 select、map 做重组足以覆盖日常 API 与运维九成场景。验证环境jq 1.7 · yq 4.x · bash · Linux / macOS / WSL