jq 命令行 JSON 处理实战指南：从安装到搞定真实接口数据

jq 命令行 JSON 处理实战指南：从安装到搞定真实接口数据

【免费下载链接】jqCommand-line JSON processor项目地址: https://gitcode.com/GitHub_Trending/jq/jq

处理嵌套 JSON 最痛苦的，从来不是"读不懂"，而是"取不到"：接口返回几千行，你只想要其中一个字段；日志里混着几十个 JSON 对象，你想把它们挑出来算个总和。jq就是干这个的——一个命令行 JSON 处理器，你给它一句简短的"查询语句"，它就帮你把数据挑出来、算出来、变形成你要的样子。

装好它之后，你会发现很多以前要写十行 Python 的场景，一条命令就够了。

三分钟装好，跑通第一条命令

jq 是纯 C 写的，没有运行时依赖，装上就能用。

包管理器是最快的路：

# Debian/Ubuntu sudo apt install jq # macOS brew install jq

想自己编译也行，仓库地址是 https://gitcode.com/gh_mirrors/jq/jq ，clone 下来按 README 里的步骤./configure && make即可。

装完先验证一下，再跑第一条真正的命令：

echo '{"name":"Alice","age":30}' | jq '.name'

输出就一行："Alice"。重点看这个引号——它告诉你输出的是 JSON 字符串，不是裸文本。

先认识两个最常用的开关：-r 和 -c

jq 默认输出是"标准 JSON 风格"的：字符串带引号、对象展开成多行。实际干活时经常想要更干净或更紧凑的结果，两个开关各解决一半：

-r（raw output）去掉字符串的引号，适合直接当普通文本用：

echo '{"msg":"hello"}' | jq -r '.msg'

输出是hello，没有引号。

-c（compact output）把多行对象压成一行，方便管道传给下一个程序：

echo '[{"a":1},{"b":2}]' | jq -c '.[0]'

输出{"a":1}，单行，直接| 传给下一层不串行。

字段路径怎么写：jq 的"寻路"语法

jq 的过滤器本质上就是在描述一条取值路径，记住三种写法就能覆盖八成场景：

• .name：取字段
• .users[0]或.users[].id：下标遍历
• .["weird-name"]：字段名带连字符时

比如一个接口返回用户列表，你要所有人的邮箱：

echo '{"users":[{"id":1,"email":"a@x.com"},{"id":2,"email":"b@x.com"}]}' \ | jq '.users[].email'

输出两行带引号的邮箱。如果字段可能不存在，加个?就不会报错而是返回null：jq '.missing?'。

干两件事真实的事：筛选和求和

筛选用select，它接收一个条件表达式，满足才输出：

echo '[{"name":"Ada","age":34},{"name":"Zoe","age":16}]' \ | jq -r '.[] | select(.age >= 18) | .name'

只输出Ada。注意中间那根|：它把上一步的结果喂给下一步，这就是 jq 全部"循环逻辑"的来源——不用写 for，管道串起来就行。

统计则把数组拍平再聚合：

echo '[{"price":29.9},{"price":5.5}]' | jq 'map(.price) | add'

输出35.4。map负责提取每个元素的价格，add负责加总，两词完事。

传参数给 jq 程序：--arg

写脚本时，值往往来自外部变量。用--arg传字符串、--argjson传 JSON 值，程序里用$名字引用：

jq -n --arg city 杭州 '{city: $city, visited: true}'

输出{"city":"杭州","visited":true}。这里-n表示不读任何输入、以null起步，适合"凭空造一个 JSON"的场景。

两个细节：字符串参数永远按字符串处理，不会被 shell 引号干扰；而--argjson传入的必须是合法 JSON，传个裸数字就会报错——这正是它防呆的地方。

把过滤器存成文件，脚本化用起来

写到十几行的过滤器还塞在 shell 命令里就很丑了。jq 支持把程序放进文件，用-f执行：

jq -f filter.jq data.json

复杂逻辑（比如先def一个自定义函数再复用）都该这么放。自定义函数和try/catch错误处理，官方手册里有完整章节可以查：docs/content/manual/manual.yml 。

还有两个值得知道的小开关：

• -S：按键名字母序输出对象，方便做文件 diff
• -e：输出结果为false或null时返回非零退出码，适合写"这个字段存在吗"的判断逻辑

echo '{"token":"abc"}' | jq -e '.token' >/dev/null && echo "有 token"

下一步去哪

• 语法拿不准时，先jq --help看一眼全部选项，比翻手册快
• 想动手试错又不想改本地文件，官方手册里描述的过滤器模型（manual 首页）值得通读一遍
• 仓库里的tests/jq.test本身就是一本"示例集"，里面是维护者长期验证过的真实用例，照着读比看教程见效更快
• 遇到"这个数组怎么拍平""怎么合并两个对象"这类具体问题，直接搜 builtin.jq 里的内置函数名，每个函数都是文档

【免费下载链接】jqCommand-line JSON processor项目地址: https://gitcode.com/GitHub_Trending/jq/jq