jq 是 Linux/Unix/FreeBSD 系统中功能强大的轻量级 JSON 处理器，专门用于解析、转换和格式化 JSON 数据。通过简洁的查询语法，jq 可以高效处理 API 响应、配置文件等结构化数据，是开发者和运维人员的必备工具。本教程全面解析 jq 的核心功能、安装方法和高级应用技巧。

jq 命令释义

jq ( JSON Query Processor ) 是一个基于命令行的 JSON 处理工具：

  • 🧩 数据提取：使用路径表达式查询 JSON 元素
  • 🔄 格式转换：修改 JSON 结构或转换为其他格式
  • 🧠 数据操作：支持过滤、映射、归约等复杂操作
  • 🎨 输出美化：格式化压缩的 JSON 数据
  • 📊 统计分析：计算聚合值和数据指标

ℹ️ jq 使用类似 JavaScript 的语法但更简洁，支持管道式数据处理

jq 命令语法

jq [OPTIONS] FILTER [FILE...]
jq [OPTIONS] -f FILTERFILE [FILE...]
  • FILTER：处理 JSON 的查询表达式（必需）
  • [FILE...]：输入的 JSON 文件（可多个，不指定则读取 stdin）
  • [OPTIONS]：控制处理行为的选项（详见下方）
  • -f FILTERFILE：从文件读取过滤器脚本

jq 命令示例

1. 基础属性提取

echo '{"name":"Alice","age":30}' | jq '.name'
  • 过滤器说明：.name 提取 name 属性
  • 输出结果："Alice"
  • 适用场景：快速获取 API 响应的特定字段

2. JSON 美化输出

curl -s https://api.github.com/users/octocat | jq '.'
  • 过滤器说明：. 表示整个输入对象
  • 功能说明：将压缩 JSON 转换为易读格式
  • 输出效果：
{
    "login": "octocat",
    "id": 583231,
    "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=4",
    ...
}

3. 数组迭代处理

echo '[{"id":1,"active":true},{"id":2,"active":false}]' | jq '.[] | select(.active==true)'
  • 过滤器说明：
    • .[]：展开数组元素
    • select(.active==true)：筛选 active 为 true 的对象
  • 输出结果：{"id":1,"active":true}
  • 适用场景：过滤符合条件的 JSON 数组元素

4. 数据转换与计算

echo '{"products":[{"name":"A","price":25},{"name":"B","price":40}]}' | jq '.products | map(.price * 1.2) | add'
  • 过滤器说明：
    • map(.price * 1.2)：为每个产品计算含税价（20%税率）
    • add：对结果数组求和
  • 输出结果：78
  • 适用场景：JSON 数据的统计分析

5. 复杂结构重构

curl -s https://api.coingecko.com/api/v3/coins/bitcoin | jq '{name, symbol, current_price: .market_data.current_price.usd}'
  • 过滤器说明：创建新对象并映射字段
  • 适用场景：API 数据精简与重构
  • 输出效果：
{
    "name": "Bitcoin",
    "symbol": "btc",
    "current_price": 23456.78
}

命令选项详解

短选项 长选项 说明
-c --compact-output 紧凑输出（单行 JSON）
-r --raw-output 输出原始字符串（非 JSON 格式）
-s --slurp 将输入流读取为单个数组
-f FILE --from-file FILE 从文件读取过滤器
-L PATH --search-path PATH 设置模块搜索路径
--arg VAR VAL - 定义变量（VAL 作为字符串）
--argjson VAR JSON - 定义变量（JSON 作为 JSON 对象）
--slurpfile VAR FILE - 将文件内容读取到变量
--indent N - 设置缩进空格数（默认 2）
--color-output - 启用彩色输出
--monochrome-output - 禁用彩色输出
-M --mono 单色输出（兼容别名）
-S --sort-keys 对象按键名排序
-j --join-output 连续输出无换行
-n --null-input 使用 null 作为输入
-R --raw-input 将输入视为原始字符串
-C --csv 输出 CSV 格式
--tab - 使用制表符缩进
-V --version 显示版本信息

系统安装说明

Debian / Ubuntu

sudo apt update
sudo apt install jq

RHEL / AlmaLinux / Rocky Linux

sudo yum install jq    # RHEL/CentOS 7
sudo dnf install jq    # RHEL 8+/Alma/Rocky

FreeBSD

sudo pkg install jq

Arch Linux

sudo pacman -S jq

📌 验证安装：jq --version

相似命令对比

命令 JSON 支持 查询语法 流处理 学习曲线
jq ✅ 完整 ✅ 强大 ✅ 优秀 ⭐⭐⭐
grep ❌ 有限 ❌ 无 ✅ 优秀 ⭐
awk ⚠️ 基础 ⚠️ 基础 ✅ 优秀 ⭐⭐⭐⭐
python -m json.tool ✅ 完整 ❌ 无 ❌ 差 ⭐⭐
yq ⚠️ 部分 ⚠️ 部分 ✅ 优秀 ⭐⭐

结语

jq 是处理 JSON 数据的终极利器，核心优势：

  1. 高效查询：复杂 JSON 路径的简洁表达
  2. 流式处理：支持管道操作和链式过滤
  3. 格式转换：轻松实现 JSON / CSV / TSV 互转
  4. 跨平台：兼容所有主流 *nix 系统

最佳实践：

# 监控 Docker 容器状态
docker stats --no-stream --format json | jq -s 'map({name: .Name, cpu: .CPUPerc, mem: .MemPerc})'

# 分析日志中的 JSON 数据
tail -f /var/log/app.log | grep "REQUEST" | jq '{timestamp, method, path}'

# 批量处理配置文件
find /etc/apps/ -name "*.json" | xargs -I{} jq '.timeout *= 2' {} > {}.new

💡 专业提示：使用 jq play (https://jqplay.org) 在线测试过滤器