jq命令详解

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 秒版）

1. 只看结构→jq .或jq -C .彩色格式化。
2. 提一个字段给脚本→jq -r '.name'。
3. 筛数组→.items[] | select(.status == "ok")。
4. 改字段不改文件→jq '.age += 1'输出到新文件或管道。
5. 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. 过滤 select
• 5. 构造与变换
• 6. 常用内置函数
• 7. 常用选项
• 8. 实战场景
• 9. jq、grep 与 yq
• 10. 常见坑
• 11. 何时不必用 jq
• 12. 延伸阅读

1. 安装与调用

jq[选项]'<jq表达式>'文件.jsoncat文件.json|jq'<jq表达式>'curl-sURL|jq'<jq表达式>'

2. 示例数据

下文示例统一使用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 格式化与类型

3.2 对象字段与数组下标

jq'.name'data.json# "Alice"jq'.address.city'data.json# "Beijing"jq-r'.name'data.json# Alice （-r 去掉 JSON 引号，适合 shell 变量）jq'.skills[0]'data.json# "jq"jq'.skills[-1]'data.json# "python"jq'.skills | length'data.json# 3

字段可能不存在时用//默认值：

jq'.phone // "N/A"'data.json# "N/A"

3.3 展开数组与管道

jq'.skills[]'data.json

"jq" "bash" "python"

对象键值：

jq'keys'data.json# ["address", "age", "name", "skills"]jq'to_entries[] | .key'data.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# "bash"jq'.items[] | select(.status == "ok")'users.json

第二条输出两行对象（Alice、Bob）。若写成jq '.items | select(.status == "ok")'则错误——此时.是整个数组，不是元素。

4.2 根对象过滤（单对象 JSON）

jq'select(.age > 20)'data.json

年龄 ≤ 20 时 jq 无输出（该条被丢弃）。

4.3 多条件

jq'select(.age > 20 and .name == "Alice")'data.json jq'.items[] | select(.age >= 18 and .status == "ok")'users.json# 仅 Alice

5. 构造与变换

5.1 生成新对象

jq'{user: .name, location: .address.city}'data.json

{"user":"Alice","location":"Beijing"}

5.2 修改字段（不可变风格）

jq'.age += 1'data.json jq'.skills += ["go"]'data.json jq'del(.address.zip)'data.json

输出为新 JSON，原文件不变；写回需重定向：jq ... data.json > data.new.json，或jq ... file | sponge file（moreutils）。

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. 常用内置函数

jq'.skills | join(", ")'data.json# "jq, bash, python"jq'.items | group_by(.status)'users.json# [{"status":"fail",...}, {"status":"ok",...}] 两组

7. 常用选项

# slurp：多个 JSON 文件合并为一个数组jq-s'.'a.json b.json# 外部变量jq--argprefix"user"'{id: ($prefix + "_" + .name)}'data.json# {"id": "user_Alice"}

--stream（进阶）

日常 API /kubectl响应无需--stream。仅当单文件数百 MB、无法一次jq .载入时考虑：

# 流式输出 [路径, 值] 对；路径末级为叶子时 length==2jq--stream'select(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 Kubernetes

kubectl get pods-ojson\|jq'.items[] | select(.status.phase != "Running") | .metadata.name'kubectl get pod my-pod-ojson\|jq-r'.spec.containers[].image'

YAML 清单常用兄弟工具yq（见 §9）。

8.3 统计与聚合

jq'.items | length'users.json# 3jq'[.items[].age] | add / length'users.json# 24（平均年龄）jq'[.items[] | select(.status=="fail")] | length'users.json# 1

8.4 CI / 日志一行 JSON

grep'^{'app.log|jq-c'select(.level == "ERROR") | {ts, msg}'

CI 脚本建议开头：

set-euopipefail# ...if!jq-e'.build.passed == true'report.json>/dev/null;thenecho"build failed">&2;exit1fi

避免jq解析失败或-e判假时被管道静默吞掉。

8.5 与 shell 变量

name=$(jq-r'.name'data.json)ifjq-e'.age >= 18'data.json>/dev/null;thenecho"adult";fi

9. jq、grep 与 yq

错误：curl ... | grep '"name"' # 易匹配错字段、无法处理嵌套 正确：curl ... | jq -r '.name'

JSON Lines（每行一个 JSON）常用jq -c或逐行管道。

10. 常见坑

11. 何时不必用 jq

jq 的定位是：命令行上的 JSON 瑞士军刀——快、声明式、管道友好；不是通用数据处理平台。

12. 延伸阅读

复杂过滤器可先在 jq play 验证，再写入脚本；生产脚本对-e与exit code做好判断，避免静默失败。

收束：jq 把 JSON 当成有类型的数据结构来切，而不是文本行；记住引号包表达式、-r给 shell、数组先[]再 select、map 做重组，足以覆盖日常 API 与运维九成场景。

验证环境：jq 1.7 · yq 4.x · bash · Linux / macOS / WSL