jq 处理大文件 JSON:-s 为什么爆内存,流式怎么写
结论:几百 MB 的 JSON 日志用 jq -s 聚合直接被系统杀掉,换成 reduce inputs 后同样的统计内存只要几 MB。本文用 220MB、200 万行样本实测两种写法的耗时与内存峰值,讲清 -s 和整体解析吃内存的机制、JSONL 逐行处理的正道、--stream 路径事件的写法,以及 -n --stream 静默零输出等三个真实的坑。

jq 本身解析得很快,让它在几百 MB 的文件上翻车的几乎总是同一个写法:
-s把整个文件读进内存拼成一个大数组,内存峰值轻松冲到文件体积的几倍到十倍。
一、现象:同一份文件,两种写法差 580 倍内存
先看一组实测。样本是 220MB、200 万行的 JSONL 日志(每行一个请求记录,含时间戳、level、path、status、duration_ms、uid 六个字段),环境是 jq 1.7、Linux x86_64,用 /usr/bin/time -v 取峰值 RSS:
| 写法 | 任务 | 耗时 | 峰值内存 |
|---|---|---|---|
jq -s 'group_by(.level) | ...' |
全量聚合计数 | 10.1s | 2.08 GB(约 9.5 倍文件体积) |
jq -n 'reduce inputs ...' |
同样的聚合计数 | 4.7s | 3.5 MB |
jq -r 'select(...) | .path' |
逐行过滤取列 | 2.6s | 3.6 MB |
同一个统计需求,换个写法内存差 580 倍,耗时还更短。这不是 jq 的 bug,-s 的语义本来就是把全部输入变成一个值——只是大部分人写聚合时没意识到这个默认代价。第三方数据也能对上:华为云社区的 2.3GB JSONL 复盘记录了完全相同的轨迹,-s 一把梭 OOM,改成流式后 47 秒跑完、RSS 30MB 出头;dratini.tech 在 2.5GB 样本上测到 jq -s 直接被 OOM killer 杀掉(>16GB 内存的机器),而标准管道 48.2 秒、84MB 跑完。
结论先行:文件大于可用内存的一半,就别考虑 -s。动手前先量三行:ls -lh 看体积、free -m 看可用内存、wc -l 看行数。
二、-s 与整体解析为什么吃内存
jq -s(slurp)的官方定义是「把全部输入读进来,放进一个数组」。实际开销远不止文本本身:jq 解析后维护的是 C 结构体组成的树,每个对象、数组、字符串、数字都有自己的节点和元数据。220MB 的文本解析成结构后是 2GB 出头——膨胀约 9.5 倍。group_by 还要在内存里排序分桶,进一步放大峰值。
单文档大 JSON 同理。把同一份日志用 jq -s '.' 拼成 300MB 的顶层大数组,再用普通过滤器 .[] | select(...) 提取:
| 写法 | 耗时 | 峰值内存 |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid'(整体解析) |
4.7s | 1.85 GB |
jq --stream 'select(...)'(路径事件流) |
13.4s | 3.4 MB |
整体解析的内存峰值仍然在 1.8GB 量级——jq 必须先把整棵树建完才开始跑过滤器。--stream 用约 3 倍的耗时换 540 倍的内存差距,这就是流式模式存在的意义。内存为什么涨得这么狠、在哪些环节涨,内存占用从哪来那篇有更完整的模型,这里只记结论。
三、JSONL 日志:默认逐行读才是正道
如果你的「大文件」其实是一行一个对象的 JSONL 日志,那 jq 的默认行为就是流式的——每个输入行独立解析、独立输出,根本不需要 -s:
# 统计每种 level 的条数:逐行读,配合 shell 聚合
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head
# 过滤 + 取列:select 放最前面,解析完立刻丢弃不匹配的行
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5
两个细节值得刻意养成习惯:
select放在管道最前。jq 解析完一行立刻过滤,被丢弃的行不会做后续构造;把过滤放在变换之后等于白算。-r输出裸字符串。不加-r,输出是带引号的 JSON 字符串,uniq -c会把"ERROR"和ERROR当成两种值。
脏行处理用 fromjson?:jq -r 'fromjson? | .level'——解析失败的行静默跳过,日志文件里混进截断行时不至于整条管道断掉。JSONL 格式本身的规则与场景选择见 JSONL 文件实操,那篇讲格式,本篇讲处理它的具体命令。
四、全局聚合:reduce inputs 流式累加
逐行过滤交给 shell 够用,但如果要在 jq 内部完成全局聚合(比如按 level 计数、按 path 算平均耗时),关键是用 reduce 配 inputs 让状态有界:
# 按 level 计数:内存只跟结果集大小有关,与文件体积无关
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl
# 按 path 聚合平均耗时:状态是 {count, total} 两个字段
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
| map_values(.total / .count)' app.jsonl
两个要点:
-n表示不把第一个输入当初始值,让inputs自己逐个吐出全部记录;漏写-n,第一条记录会被当初始值吃掉。- reducer 的状态必须定形——只维护计数器、累加值这类固定字段。一旦在 reducer 里把匹配行 push 进数组,内存又会跟着数据量涨回去,流式就白做了。
这就是上面表格里 3.5MB 的来源:2GB 的数据流过,留下的只有一个哈希表。
五、单文档大数组:--stream 的路径事件
当输入是「一个巨大的顶层文档」(比如几百 MB 的导出文件),没有行边界可逐行读,这时用 --stream。它不再输出完整的值,而是输出一系列「路径 + 叶子值」事件:
# 事件长这样:路径数组 + 标量值
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"
从事件流里提取字段,要匹配完整路径形状——深度、成员名、数组下标位置都要核对,只看最后一段会捞进嵌套对象里的同名字段:
# 只取 rows[i].id,跳过 meta.id 和更深处的同名键
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json
聚合依然走 reduce inputs 的定形状态写法(-n 配 --stream 时必须用 inputs 消费事件,见下一节的坑)。更复杂的重组需求(把匹配事件流还原成完整对象)用 truncate_stream 配 fromstream:先截掉前几层路径,再由 fromstream 按子树重组,华为云社区那篇有完整示例。
--stream 的代价是慢:路径事件要把结构展开成一条条标量,同任务耗时约是整体解析的 3 倍。所以决策顺序是:JSONL 优先逐行;单文档且目标只是提取少量叶子值,才上 --stream。大文件怎么按体积选工具的总览在大文件 JSON 打不开怎么办。
六、三个真实的坑
坑一:-n --stream 不配 inputs,静默零输出。 本机实测踩到的:jq -n --stream 'select(...)' file.json 退出码 0、无任何输出、无任何报错——因为 -n 模式下 jq 不会自动读输入,过滤器里的 select 根本没有事件可挑。正确写法是去掉 -n 直接 --stream,或者 -n --stream 配 reduce inputs / inputs 显式消费。这类「成功但空」的失败最难排查,写管道时先拿小样本验证有输出。
坑二:--stream 只给标量叶子,空对象和空数组没有值事件。 {"a":{}} 只会产生路径结束标记(length == 1 的事件),如果过滤器只匹配 length == 2,空容器会被静默吞掉。统计口径里要不要算空容器,要显式写进过滤条件。
坑三:中途 parse error 会不会发布部分结果。 流式管道可能已经吐出前半段结果,随后在文件尾部遇到坏 JSON 才失败。jq 1.7 默认直接报错退出(实测 [1,] 触发 parse error: Expected another array element at line 1, column 4,退出码 5),但如果你在 shell 里把输出重定向到了目标文件,残缺文件已经落盘。工程做法是 staging + rename:先写到临时文件,jq 成功后再 mv 覆盖目标;需要更细的控制用 --stream-errors 把解析错误也当事件处理,在过滤器里显式 error 中断。jsonprettifier 的文章给了完整的原子发布模板。
七、什么时候别用 jq:Miller 与混合管道
jq 是函数式树变换语言,擅长深嵌套改写和结构重组;但当任务退化成「GB 级扁平日志的过滤和统计」时,有更对口的工具。dratini.tech 在 2.5GB JSONL 上的基准(过滤 + 取列):
| 工具 | 耗时 | 峰值内存 |
|---|---|---|
| jq 标准管道 | 48.2s | 84 MB |
| jq -s | OOM(>16GB 内存被杀) | — |
| Miller(mlr --json) | 11.4s | 18 MB |
| ripgrep + jq 混合 | 8.1s | 32 MB |
选型口诀:深嵌套、结构变换、CI 里到处都有 jq——用它;多 GB 的扁平 JSONL 统计、p95 分位数、JSONL 转 TSV——Miller 一条 mlr --json stats1 顶一段 jq 脚本,且内存恒定;rg 能先按行筛掉 90% 无关记录再交给 jq 时,混合管道最快。极端大文件的更多路线(ijson、分片、专用查看器)见大文件 JSON 打不开怎么办。
常见问题
jq -s 处理多大文件会出问题?
经验阈值是文件体积超过可用内存的一半就要警惕:解析后的内存开销通常是文本的 3-10 倍(本机 220MB 实测 9.5 倍,第三方记录 4GB 文件在 16GB 机器上直接 OOM)。先跑 ls -lh 和 free -m 对一下数字,超过就把 -s 换成 reduce inputs。
reduce inputs 前面为什么要加 -n?
-n 告诉 jq 不要把第一个输入当作程序的初始输入,让 inputs 自己逐条吐出全部记录。漏写 -n 时,第一条记录会被当作 reduce 的初始状态吃掉,结果里永远少第一条——这种丢数据的 bug 不报错,很难发现。
jq --stream 和普通模式怎么选?
先看文件形态:JSONL 日志默认逐行读就是流式的,不需要 --stream;单个大文档且只需要提取少量叶子值时,--stream 用约 3 倍耗时换数百倍内存差距,值得。需要完整重组子树时用 truncate_stream + fromstream。文件能装进内存就别折腾流式,普通写法更快。
流式处理遇到损坏的 JSON 行怎么办?
JSONL 里用 fromjson? 跳过解析失败的行,不让一条脏行断掉整条管道。单文档大 JSON 里中途 parse error 会让管道失败,用 staging 文件加 rename 做原子发布,避免把已经吐出的部分结果留在目标文件里;需要显式控制用 --stream-errors。