hereink

如何使用 jq 命令行处理 JSON：安装、筛选字段、映射数组与 curl 管道

安装 jq，提取 JSON 字段、映射数组，并用 curl 管道快速查看 API 响应。

调试 REST API 或读 CI 日志时，jq 让你在终端里直接筛选和变换 JSON，不必把整段响应贴进编辑器。本教程走 macOS、Linux 与 Windows 的官方安装路径，并演示字段提取、数组映射与 curl 管道，面向 hereink 读者常用的命令行工作流。

检索词是如何使用 jq 处理 JSON 并与 curl 管道。读完应能安装 jq、用 .key 取字段、用 map 处理数组，并把 API 响应缩成几行可读输出。

安装brew / apt / winget
筛选.field · .[] · select
管道curl -s … | jq

jq 解决什么问题

比 python -m json.tool 更灵活

内置 json.tool 只能美化。jq 可以只打印 .data.items[0].id、过滤数组、或把嵌套结构压平，适合脚本和一次性调试。

与 curl 天然搭档

API 响应往往几百行。管道末尾加 jq '.field'，终端只留你关心的键，减少滚动和复制粘贴。

确认版本：jq --version。官方站点与手册：jqlang.org，GitHub 组织 jqlang/jq。

在三大系统安装 jq

  1. 1
    macOS（Homebrew）

    执行 brew install jq。验证：which jq 与 jq --version。Apple Silicon 与 Intel 共用同一公式。

  2. 2
    Linux（发行版包）

    Debian/Ubuntu：sudo apt update && sudo apt install jq。Fedora：sudo dnf install jq。Arch：sudo pacman -S jq。若仓库版本过旧，可从 GitHub Releases 下载静态二进制。

  3. 3
    Windows

    PowerShell：winget install jqlang.jq，或 Chocolatey：choco install jq。新开终端后跑 jq --version。

  4. 4
    第一条过滤器

    测试：echo '{"ok":true,"n":3}' | jq .ok 应输出 true。全对象美化：echo '{"a":1}' | jq .。

筛选字段与映射数组

# 提取顶层键
echo '{"user":{"name":"Lin","role":"admin"}}' | jq .user.name

# 展开数组元素
echo '{"items":[{"id":1},{"id":2}]}' | jq '.items[]'

# 映射：只保留 id
echo '{"items":[{"id":1,"x":0},{"id":2,"x":1}]}' | jq '.items | map(.id)'

# 条件过滤
echo '[{"k":"a","v":1},{"k":"b","v":2}]' | jq '[.[] | select(.v > 1)]'

# 多字段一次输出
echo '{"a":1,"b":2,"c":3}' | jq '{a,b}'

过滤器用单引号包住，避免 shell 展开 $。点号 . 表示当前 JSON 值；[] 迭代数组。

与 curl 管道

场景命令示例说明
公开 API 元数据curl -s https://api.github.com/repos/jqlang/jq | jq '{name, description, stars: .stargazers_count}'只留 name、description、stars
HTTP 头 + 体curl -sD - https://httpbin.org/get | jq .若体是 JSON；混排时先分离头与体
脚本用纯文本curl -s … | jq -r '.token'-r 去掉 JSON 字符串引号
紧凑日志行curl -s … | jq -c '.items[]'每元素一行，便于 rg 再搜
适合
快速查看 REST 响应字段、过滤 CloudWatch/容器日志里的 JSON 行、CI 里解析构建元数据。
不适合
编辑并写回大 JSON 文件（考虑重定向或专用配置工具）；非 JSON 文本（先用 grep/rg）。
jq: parse error 是什么意思？

输入不是合法 JSON（多余逗号、单引号、或非 JSON 文本混在管道里）。用 jq . 单独测输入；对 NDJSON 用 jq -s 或逐行处理。

Windows 上 jq 找不到命令？

安装后重启终端。运行 where jq。winget/Chocolatey 通常会自动加入 PATH。

jq 和 yq 一样吗？

不一样。jq 专用于 JSON。YAML 需 yq 或先转格式。API 调试场景 jq 更常见。

字段对齐后画一张图

终端里理清 API 结构后，服务边界仍适合摊在同一张白板上。短会不必新工具栈，见 如何创建空间。

即刻开会