jq：轻量灵活的命令行 JSON 处理器安装与使用指南

官方信息表

配图

项目背景

jq 是一个面向命令行的 JSON 处理器，官方在 README 开篇就把它定位成 “a lightweight and flexible command-line JSON processor akin to sed, awk, grep, and friends for JSON data”——也就是为 JSON 数据量身定做的 sed、awk、grep 一类工具。它的核心价值在于：当你在终端里面对一坨又长又嵌套的 JSON 接口返回、配置文件或日志时，不需要临时写 Python 脚本、也不需要把数据粘进浏览器插件，只用一条命令就能把结构化数据切片、过滤、映射、再加工成你想要的形状。

在 jq 出现之前，运维和后端人员处理 JSON 的手段通常比较笨重：要么把输出重定向到文件再用文本编辑器翻；要么写一段 Python、Node 脚本去 import json 解析；要么干脆依赖一句又长又脆弱的 grep -o 正则去硬抠字段。这些做法要么慢、要么不可复用、要么对格式变化极其敏感。jq 的出现正是为了终结这种尴尬：它把“查询 JSON”这件事变成了一门可以在 shell 里直接书写、即写即得的微型表达式语言。

jq 用可移植的 C 语言写成，并且零运行时依赖，这意味着它编译出来的是一个独立的可执行文件，不依赖任何外部动态库就能在目标机器上跑起来。这一点对于嵌入式设备、最小化 Docker 镜像、精简的服务器环境尤其重要——你不必为了处理一段 JSON 而拖入一整套解释器运行时。也正因为如此，jq 被大量 CI 流水线、容器镜像和运维脚本直接内置，成为云原生时代处理 JSON 事实上的标准小工具。

从使用场景看，jq 最常见的用法是串联在 shell 管道里：上游程序吐出 JSON，下游用 jq 把字段抠出来、按条件筛选、再拼成新的 JSON 或纯文本喂给下一条命令。一条 curl 命令、一份 package.json、一段容器日志、一个 Kubernetes 资源清单，几乎所有带 JSON 的地方，都能看到 jq 夹在中间把数据“拆成零件”。

值得一提的是，jq 之所以能成为事实标准，和它“小而稳”的工程取舍有很大关系。它不试图做成一个大而全的数据处理框架，而是把自己定位成 shell 生态里的一块拼图：只负责把 JSON 读进来、用表达式变换、再吐出去，剩下的交给 grep、awk、sort、uniq 这些你已经熟悉的 Unix 工具。这种“做好一件事、并和其他工具组合”的设计哲学，让它在十几年里几乎没有被其他工具取代——因为替代者往往要么太重，要么要你换一套完全不同的工作方式。

核心特性逐条翻译

README 虽然不长，但开篇已经把 jq 的定位讲清楚了，下面把官方强调的要点逐条翻译并展开。

第一，轻量且灵活的命令行 JSON 处理。 jq 不是一个带界面的 JSON 编辑器，而是一个设计成可嵌入 shell 流水线的命令行工具。它可以对 JSON 做切片（slice）、过滤（filter）、映射（map）和变换（transform），你可以像写正则那样用 jq 表达式去描述“我要从这份数据里取什么、怎么改”。

第二，用可移植 C 编写，零运行时依赖。 README 明确写道 “written in portable C and has zero runtime dependencies”。这直接决定了 jq 的分发形态：官方 Release 里提供的是独立可执行文件，不是压缩包，也不需要 apt install 一串库。下载下来 chmod +x 就能用，这种“单文件可落地”的特质是它能渗透到各种极简环境的根本原因。

第三，官方同时提供文档站与在线 playground。 README 的 Documentation 一节给出两个入口：官方文档在 jqlang.org，在线试玩在 play.jqlang.org。后者允许你在浏览器里直接写 jq 表达式、粘贴样例 JSON，立刻看到结果，非常适合初学阶段边改边试，省去了“改一次表达式、存一次文件、跑一次命令”的来回。

第四，多种安装与分发方式并存。 README 给出了预编译二进制、Docker 镜像、从源码编译三条路径，覆盖了“我只想马上用”“我要放进容器”“我要定制编译”三类用户。无论你是 Windows、macOS、Linux，还是一个要打进镜像的 CI，都能找到对应的落地方式。

第五，活跃的社区与 wiki。 README 在 Community & Support 一节列出了 Stack Overflow 的 jq 标签、官方 Discord 以及 GitHub Wiki。复杂的表达式技巧、跨编译、高级用法都沉淀在 Wiki 里，遇到冷门问题基本都能搜到前人的答案。也正是因为用户基数足够大，几乎任何你能想到的 jq 表达式写法，都能在 Stack Overflow 上找到对应的讨论。

环境要求与部署

jq 的部署分成“直接用现成二进制”“用 Docker 运行”和“自己从源码编译”三条路线，README 都有明确说明，下面分别展开。

方式一：下载预编译二进制（推荐快速上手）

前往 GitHub Release 页面 下载对应平台的最新资产文件。README 特别提醒：这些平台资产是独立可执行文件，不是压缩包，不要用解压软件去解压它。在 macOS 和 Linux 上，把下载下来的文件重命名为 jq，然后赋予可执行权限即可：

chmod +x jq

把它放到 PATH 里（例如 /usr/local/bin/jq）之后，终端任意位置都能直接调用 jq。这种方式不需要任何编译器、不需要任何运行库，适合绝大多数只想“马上能用”的用户。

方式二：用 Docker 运行（无需在本机安装）

README 提供了官方容器镜像 ghcr.io/jqlang/jq，适合不想在本机装二进制、或希望在 CI 里一次性调用的场景。直接把标准输入里的 JSON 交给它处理，下面这条例子是 README 原样给出的——从 package.json 里抽取 version 字段：

docker run --rm -i ghcr.io/jqlang/jq:latest < package.json '.version'

如果要读取当前目录下的真实文件而不是标准输入，README 给了挂载卷的写法，用 -v 把当前目录挂进容器，并通过 -w 指定容器内工作目录：

docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/jqlang/jq:latest '.version' package.json

这种方式的好处是环境干净、可重复，CI 里不需要额外安装 jq，一行 docker run 就能完成 JSON 处理。

方式三：从源码编译

如果你需要定制编译选项、交叉编译，或者要给某个没有预编译包的平台移植 jq，可以走源码路线。README 列出的编译依赖是：libtool、make、automake、autoconf。如果是从 git 仓库拉的源码，需要先初始化子模块（用于获取 oniguruma 正则库），再依次执行：

git submodule update --init    # 如果从 git 构建，需要拉取 oniguruma
autoreconf -i                  # 如果从 git 构建
./configure --with-oniguruma=builtin
make clean                     # 如果之前用源码构建过，先清理
make -j8
make check
sudo make install
sudo ldconfig                  # Linux 下若 jq 找不到 libjq.so 时执行

README 还给出了静态链接版本的构建方式，适合把 jq 打进不希望依赖外部 .so 的发行包：

make clean
make LDFLAGS=-all-static

如果你下的是 Release 里的 tarball 而不是 git 源码，README 说明可以跳过 autoreconf 这一步，也不需要 flex 或 bison。关于交叉编译，README 指引参考仓库里的 GitHub Actions CI 文件 和 Cross-compilation wiki。

使用方法

安装完成后，最直接的验证方式是把一段 JSON 喂给它。例如读取 package.json 并取出 version 字段，README 给的示例就是这种形式：

jq '.version' package.json

其中 .version 就是一个 jq 过滤器：. 代表整份输入，.version 表示取根对象下的 version 字段。常见的管道用法是配合 curl 把接口返回直接交给 jq：

curl -s https://api.github.com/repos/jqlang/jq | jq '.stargazers_count'

你可以用 .[] 遍历数组、用 map() 对数组里每个元素做变换、用 select() 按条件过滤元素、用 {} 重新组装一个只含部分字段的新对象。这些语法 README 主文件没有堆砌，而是放在官方文档站和在线 playground 里。建议第一次接触时，先在 play.jqlang.org 里粘贴一份自己的真实 JSON，边写表达式边看输出，比死记语法快得多。

举几个在日常运维中最常见的用法，帮你建立直觉：如果你拿到的是一个仓库列表 JSON，只想打印每个仓库的名字，就用 '.[].name'；如果你想只保留星数超过某个阈值的仓库，就写成 '.[] | select(.stargazers_count > 10000) | .full_name'；如果你想把结果重新组装成一个新对象而不是逐个打印，就用 '{repo: .full_name, stars: .stargazers_count}'。竖线 | 在 jq 里和 shell 管道含义一致，就是把上一个过滤器的输出交给下一个过滤器，这也是它容易和 shell 流水线混用、一学就会的原因。

在 CI 或脚本里，jq 最常见的搭档是 curl -s 加 | jq，用来从接口返回里取出一个字段喂给后续命令；也常用于把 docker inspect、kubectl get -o json 这类命令的冗长输出压缩成一行可读的信息。因为 jq 零依赖、单文件，它几乎可以放进任何容器镜像或初始化脚本里，成为“处理 JSON”这一步的标准工具。

再举几个日常高频场景：你想知道一个 GitHub 仓库有多少 star，就 curl -s https://api.github.com/repos/jqlang/jq | jq .stargazers_count；你想从一份嵌套很深的 JSON 里把所有用户名抽成列表，就 jq '.[].owner.login'；你想把一份数组里每个元素只保留 name 和 id 两个字段重新组装，就 jq 'map({name, id})'。这些操作在没有 jq 的年代要么写 Python 脚本、要么用脆弱的正则，有了 jq 之后都是一行命令。README 还专门提供了在线 playground，建议你先在浏览器里把这些表达式跑一遍，建立对 jq 过滤器的直觉。

常用参数上，jq '.' 会把输入格式化缩进打印出来；jq -r 输出原始字符串而不是 JSON 带引号；jq -s 把多个输入读成一个数组；jq 'select(.age > 30)' 做条件过滤；jq 'keys' 列出对象的所有键；jq 'length' 取数组或字符串长度。它支持变量、管道、函数定义，能力接近一门小的查询语言，但学习曲线比写 Python 平得多。

常见问题（FAQ）

问：下载下来的 Release 文件打不开、解压报错怎么办？ README 明确说明这些资产是独立可执行文件，不是压缩包。在 macOS/Linux 上重命名为 jq 后执行 chmod +x jq 即可，不要用解压软件去解压它。

问：我不想在本机安装，有没有办法在容器里用？ 有。README 提供了官方镜像 ghcr.io/jqlang/jq，可以直接 docker run --rm -i ghcr.io/jqlang/jq:latest 配合标准输入使用；需要读取本地文件时用 -v "$PWD:$PWD" -w "$PWD" 把当前目录挂进容器。

问：从源码编译时提示找不到 oniguruma 或 libjq.so？ 从 git 构建必须先 git submodule update --init 拉取 oniguruma 子模块，并在 configure 时加 --with-oniguruma=builtin；安装后若在 Linux 上提示找不到 libjq.so，执行一次 sudo ldconfig 刷新动态库缓存即可。

问：我想把 jq 编译成不依赖外部库的单文件怎么做？ README 给出了静态链接方式：先 make clean，再 make LDFLAGS=-all-static，产出的二进制可直接拷到同架构的其他机器运行，无需附带任何 .so。

问：去哪里学完整的 jq 表达式语法？ README 把语法文档放在 jqlang.org，并提供 play.jqlang.org 在线试玩；遇到具体问题可以去 Stack Overflow jq 标签 搜索，高级话题看 GitHub Wiki。

问：jq 采用什么协议？商用有无限制？ jq 本体以 MIT 协议发布，可自由用于商业项目；其文档采用 CC BY 3.0；代码中使用了开源 C 库 decNumber，该部分采用 ICU License。整体上对商用非常友好。

问：jq 和 Python、Node 里的 json 库相比优势在哪？ 优势在于“零启动、零依赖、一条命令”。jq 是一个几十 MB 都不到的单文件二进制，处理一段 JSON 不需要拉起解释器、不需要安装任何包；而 Python/Node 脚本每次都要付出进程启动和依赖加载的成本。在 shell 流水线、容器镜像、最小化环境里，jq 这种“即取即用”的形态明显更轻；但如果逻辑非常复杂、需要多步关联计算，写一段 Python 脚本反而更清晰。

跳转链接

• 官方代码仓库：jqlang/jq
• 官方文档站：jqlang.org
• 在线试玩：play.jqlang.org
• 预编译版本下载：GitHub Releases
• Docker 镜像：ghcr.io/jqlang/jq
• 社区问答：Stack Overflow jq 标签
• 官方 Discord：discord.gg/yg6yjNmgAC
• 高级话题 Wiki：github.com/jqlang/jq/wiki
• 交叉编译参考：Cross-compilation wiki