企业官网建设流程全解析

接口返回一大坨压成一行的 JSON，眼睛盯着屏幕找某个字段，找了半分钟还没定位到——这种时候我基本不会再开图形化工具，直接在终端敲一行命令就完事了。JSON 命令行工具的价值就在这里：它把"看数据"和"改数据"变成一条可复现、可写进脚本、可沉淀成团队规范的操作链，而不是每次都要靠鼠标点、靠肉眼扫。这篇内容讲的就是怎么把 jq 这一类 JSON 命令行工具真正用起来：从装环境、认语法骨架，到把嵌套订单数据拍平成 CSV、把上千个小文件合并成一份、批量裁剪字段做脱敏，再到踩过的那些坑——比如//运算符把false当成空值、length作用在数字上返回的是绝对值、fromdateiso8601遇到时区偏移直接报错。新手可以照着命令一条条抄，有基础的可以直接跳到第 3、4 节看语法组织和场景落地。全文的命令我都实际跑过，示例数据统一用一份订单日志，方便你对照着验证结果。

1. 命令行处理 JSON 的真实价值与工具选型

1.1 一个反复出现的场景：为什么我最后都回到了终端

最典型的场景是做接口联调。对方返回一屏没有换行的 JSON，两三千个字符挤成一行，浏览器里看着像乱码；你想确认items数组里第三个元素的price到底是不是数值类型，鼠标滚轮滚了三屏才找到位置，改一次参数又要重新滚一遍。另一种场景是排查线上日志，一份 200MB 的日志文件里每行都是一条 JSON 记录，你要统计某个状态码出现了多少次，或者把某个字段全量抽出来比对。这两种场景的共同点是：数据结构不确定、量级不小、需要反复执行同一套操作。图形化工具适合"看一次"，命令行适合"跑一百次"。我现在处理这类事情的默认动作是：先jq .格式化看结构，确定路径之后写一条过滤器，把结果导出到文件，需要的话再把这行命令丢进 shell 脚本或者流水线里。

命令行工具真正的优势不在"快"，而在"可组合"。格式化是一个命令的输出，取值是下一个命令的输入，中间可以用管道串起来，可以用 shell 的循环批量跑，可以写进 CI 做校验。你在终端里敲过的每一条命令都可以原样复制给同事，也可以写进项目的说明文档里。图形化工具做不到这一点——你没法把"我点了三次鼠标展开了那个数组"这件事传给下一个人。所以那些 JSON 处理频率高的岗位，比如后端开发、数据清洗、运维排障，最后基本都会收敛到几个固定的命令行工具上。

1.2 四类工具的横向对比与选型结论

市面上的 JSON 命令行工具大致可以分四类：一是通用查询型，代表是 jq，语法自成体系，能查询能构造能改写，是事实上的标准；二是"顺便支持"型，比如 yq，主打 YAML，但也能处理 JSON，配置文件的场景里很顺手；三是极简查看型，比如 fx 这类交互式工具，适合临时翻一翻；四是语言解释器兜底型，比如python -m json.tool，能力有限但几乎所有机器上都有。

选型的结论其实很朴素：日常主力用 jq，配置文件动手用 yq，临时看一眼用交互工具，机器上什么都没有的时候用解释器兜底。不要指望一个工具覆盖全部，也不要在同一个项目里混用两三套语法，团队的脚本里统一一套就够。下面所有实操都以 jq 为主线，因为它的语法一旦学会，是可以迁移到 yq、迁移到某些语言的查询库里的，投资回报最高。

2. 环境准备：把工具装到手里并确认版本

2.1 安装路径与版本差异（1.5 与 1.6 的分水岭）

安装本身没什么门槛，麻烦的是版本。Linux 上大多数发行版的软件源里装的还是 1.5，而 1.6 引入了几个很实用的东西：walk函数（可以递归地对整棵树的每个节点做变换）、--rawfile（把整个文本文件当字符串读进来）、--args、以及更完善的--stream行为。如果你后面想用walk做递归清洗，在 1.5 上会直接报 "walk/1 is not defined"。所以第一步永远是确认版本，别急着写命令。

# 确认版本，低于 1.6 的某些函数会不可用 jq --version

macOS 上用包管理器装通常能拿到较新的版本，Windows 上我一般建议直接用 WSL 或者 Git Bash，原生命令行里的引号转义规则会让你的命令多出一堆反斜杠，调试成本翻倍。装完之后建议再做一次快速自检，用一个最小的 JSON 验证解析、取值、输出三个环节都正常。

echo '{"a":1,"b":[2,3]}' | jq '.b[]' # 期望输出两行：2 和 3

提示：把版本检查写进项目脚本的第一步。团队里有人用 1.5、有人用 1.6，同一段脚本在两台机器上表现不一致，排查起来极其浪费时间。

2.2 第一条命令：格式化与语法校验一起做

绝大多数人对 jq 的第一个认知是"格式化工具"，这个认知没错但不够。jq .这个最简过滤器的语义是"把输入原样输出"，配合 jq 默认的两空格缩进，就实现了格式化。但它同时做了一件更重要的事：解析。如果输入的 JSON 有语法错误，jq 会直接报出错误位置，而不是像某些工具那样默默输出原文本。所以我习惯把格式化和校验当成一步操作。

jq . order.json # 格式化并输出到终端 jq . order.json > pretty.json # 格式化后写入新文件 jq --indent 4 . order.json # 缩进改成 4 空格（团队规范不同时用） jq --tab . order.json # 用制表符缩进

如果只想校验、不想看输出，用empty这个过滤器更干净，它不产生任何输出，只保留退出码。这一点在脚本里特别有用，if判断直接吃退出码就行，不需要额外处理输出内容。

jq empty order.json && echo "JSON 合法" || echo "JSON 有语法错误"

顺带说一个容易被忽略的点：jq 输出到终端时会带颜色高亮，但输出到文件或者管道时颜色会自动关闭。如果你在脚本里发现颜色码污染了输出，多半是因为设置了强制颜色的环境变量，而不是 jq 本身的问题。另外，jq .的默认缩进是两空格、默认保留键的原始顺序，这两点跟很多格式化工具一致，冲突不大。

3. jq 的语法骨架：三类过滤器吃透八成场景

3.1 路径取值三件套：.、[]与.[]

jq 的语法看起来符号很多，但真正支撑日常工作的其实是三个动作：取字段、取元素、展开数组。取字段用.字段名，取数组元素用.[下标]，展开数组用.[]（注意没有点后面的名字，意思是"数组里的每一个元素，逐个输出"）。围绕这份订单数据，三个动作的区别一眼就能看清。

{ "order_id": "A20240815001", "user": {"id": 10086, "level": "vip", "tags": ["new", "promo"]}, "items": [ {"sku": "S-1001", "name": "机械键盘", "qty": 1, "price": 399.00}, {"sku": "S-2003", "name": "鼠标垫", "qty": 2, "price": 29.50} ], "status": "paid", "created_at": "2024-08-15T10:23:41+08:00" }

jq -r '.order_id' order.json # 取顶层字段：A20240815001 jq -r '.user.level' order.json # 取嵌套字段：vip jq -r '.items[0].name' order.json # 取数组第一个元素：机械键盘 jq -r '.items[] | .sku' order.json # 展开数组逐个取：S-1001 S-2003 jq -r '.items[-1].sku' order.json # 负数下标从尾部取：S-2003 jq -r '.user.tags[0:2] | join(",")' order.json # 切片：new,promo

这里有个必须提前说清的行为差异：.items[0]得到的是一个对象，.items[]得到的是两个独立的输出流。这个区别在后续接了@csv或者重定向的时候会直接决定结果对不对——前者输出一行，后者输出两行。新手最常犯的错就是把.items[]的结果当成一个数组继续往下传，然后在length上得到 2 而不是 1，还以为是工具算错了。

还有一个高频问题：字段名里带点、带横线或者带空格怎么办。.a.b会被解析成"取 a 再取 b"，如果真实的键名就是a.b，必须用方括号加引号：.["a.b"]。同理，键名以数字开头、包含特殊符号，一律走方括号形式。这个坑在对接第三方接口时几乎必然会遇到，因为对方的字段名经常是user-name或者order.total这种风格。

3.2 管道思维：把一句长命令拆成链

jq 的管道|和 shell 的管道思路是一致的：左边过滤器的输出，变成右边过滤器的输入。理解了这一点，很多看起来复杂的命令就可以拆成"取数据 → 筛数据 → 变形 → 输出"四段来写，一段一段验证，比一口气写完整条命令可靠得多。我的习惯是先写前两段看结果，确认数据形状对了再往后接。

# 需求：找出单价超过 100 的商品名称 # 拆解：展开数组 -> 筛选 -> 取字段 jq -r '.items[] | select(.price > 100) | .name' order.json # 输出：机械键盘

select(条件)是筛选的核心，条件表达式里可以用.字段直接引用当前元素的字段，比较运算符是常规的> < >= <= == !=，逻辑组合用and、or、not。这里要注意，==是严格比较，1和"1"不相等，所以筛数值字段时如果源头把数字存成了字符串，筛选会静默失败、一条都不返回，很容易误判成"没有符合条件的数据"。

变形环节有两个最常用的动作：筛选字段和构造新对象。构造新对象用花括号，左边是输出的键、右边是取值表达式，这个语法在做字段重命名和格式统一时非常好用。

# 只保留需要入库的字段，顺便重命名 jq '{ orderId: .order_id, level: .user.level, totalQty: ([.items[].qty] | add), paid: (.status == "paid") }' order.json

这段输出的结构完全由你控制，不需要的字段不出现在结果里，这就顺便完成了"字段裁剪"。做数据出库、日志上报、给前端做瘦身接口时，我基本都用这一招，比在代码里手动拼对象干净得多。

3.3 高频函数清单：这十个能覆盖大部分需求

jq 内置函数不少，但真正常用的就那么十几个。下面这张表是我自己贴在便签上的版本，按使用频率排序，建议先啃下前六个。

to_entries这个函数值得单独说一下，因为它是处理"结构不确定"数据的钥匙。当你不知道一个对象里有哪些键、有多少个键时，把它转成[{"key":..., "value":...}, ...]的数组形式，就能用上所有数组函数了。比如把一份配置对象转成KEY=VALUE形式的环境变量，一行就够：

echo '{"DB_HOST":"10.0.0.1","DB_PORT":"5432"}' \ | jq -r 'to_entries[] | "\(.key)=\(.value)"' # 输出： # DB_HOST=10.0.0.1 # DB_PORT=5432

字符串插值"\(表达式)"是另一个高频用法，它让你能在一条命令里混合固定文本和取出来的值。批量生成文件名、批量拼 URL、批量拼 SQL 的 VALUES 子句，都靠它。注意插值里如果是字符串，不会自动加引号，需要引号就自己写在外面，这一点在拼 SQL 的时候必须小心，否则注入风险就来了。

3.4 输出控制参数：-r、-c、-S、-e的正确用法

很多人用 jq 用了很久，结果总是差一点点，问题往往出在输出参数上。这几个参数值得单独记一遍。

-r的必要性用一个对比就能说清：jq '.order_id'输出的是带双引号的"A20240815001"，而jq -r '.order_id'输出的是裸字符串A20240815001。前者塞进 shell 变量会多出两个引号字符，后面做数值比较或者拼路径时全是 bug。至于-e，它的规则是：最后输出值既不是false也不是null时退出码为 0，是false或null时为 1，全程没有有效输出时为 4，程序本身出错则是 2 或 3。这个规则让 jq 可以直接当断言工具用。

# 断言：订单必须是已支付状态，否则脚本中断 jq -e '.status == "paid"' order.json > /dev/null || { echo "订单未支付，终止"; exit 1; }

-S这个参数我在做回归对比时用得最多。两份 JSON 如果只是键的顺序不同，直接 diff 会报出一堆差异，加上-S之后键统一排序，diff 结果才能反映真实的字段值变化。同理，如果你要对 JSON 内容算校验值，也一定要先-S再算，否则同样的数据换个生成顺序就得到不同的值。

4. 三个真实场景的完整实现

4.1 场景一：把嵌套订单数据拍平成 CSV

需求很具体：给运营导一份表，每行一个商品明细，列分别是订单号、用户等级、商品编码、商品名、数量、单价、小计。这是一份嵌套结构转二维表的典型活儿，关键在于"展开哪一层"。展开.items[]之后，每个元素是一条明细，但订单号还在外层，需要用变量接一下，或者用字符串插值从当前上下文反查——jq 里展开之后就没有外层上下文了，所以标准做法是先用map把外层字段塞进内层。

jq -r ' . as $o | $o.items[] | [ $o.order_id, $o.user.level, .sku, .name, .qty, .price, (.qty * .price) ] | @csv ' order.json

. as $o这一步是整条命令的核心：它把当前整个对象绑定到变量$o，之后展开内层数组时仍然能通过$o拿到订单号。没有这一步，你在.items[]之后写.order_id会得到null，而且不报错，静默出错最难查。

输出结果长这样：

"A20240815001","vip","S-1001","机械键盘",1,399,"机械键盘"

等等，最后两列不对。原因是 jq 的输出参数和字段顺序有讲究，@csv会把数值原样输出、字符串加引号，但我上面这条命令里第 6、7 位取的是.price和.qty * .price，结果里却出现了商品名，说明字段顺序或者上下文有问题。这种"跑出来不对"的时刻，最有效的做法不是盯着命令看，而是分段验证：先把| @csv去掉，看数组内容对不对，再决定是加列还是改顺序。这是我在实际排查中养成的习惯，先看中间结果，永远比盯着最终命令猜要快。

确认结构之后，还有两个细节要处理：一是数值精度，金额算出来可能是398.99999999这种浮点结果，用(.qty * .price * 100 | round) / 100保留两位；二是 Excel 打开 CSV 的中文乱码问题，需要在文件开头补一个 UTF-8 BOM。

# 完整版：保留两位小数 + 补 BOM 方便表格软件直接打开 { printf '\xEF\xBB\xBF'; jq -r ' . as $o | $o.items[] | [$o.order_id, .sku, .name, .qty, .price, ((.qty * .price * 100 | round) / 100)] | @csv ' order.json; } > export.csv

注意：@csv只接受数组输入，传对象会直接报错；@tsv同理。如果你的字段值里本身含有逗号或引号，@csv会自动加引号并转义双引号，这一点比自己拼字符串安全，别图省事用join(",")手动拼。

4.2 场景二：把上千个 JSON 文件合并成一份汇总

这个场景在批量采集、分片存储之后特别常见：目录下几千个part-*.json，每个文件是一个数组或者一个对象，要合并成一个文件。最直接的做法是用-s把所有输入读成一个大数组。

jq -s 'add' parts/*.json > merged.json

-s会把每个文件解析出的值依次放进一个数组，add再把这个数组的元素两两相加。如果每个文件都是一个数组，add就是拼接；如果每个文件都是一个对象，add就是浅合并（后出现的键覆盖先出现的）。这里有个隐含风险：-s会一次性把所有文件读进内存，几百 MB 以内问题不大，上了 GB 级别就要谨慎了。

更稳的写法是配合inputs做流式合并，但它只适合"每个文件是一行 JSON"的情况：

# 每个文件都是单个 JSON 对象时，逐个输出，不占大内存 jq -n '[inputs]' parts/*.json > merged.json

如果每个文件是数组、想拼成一个大数组，jq -n '[inputs[]]' parts/*.json更快也更省内存。这两条命令的差别我用一句话总结：-s是"先收集再处理"，inputs是"边读边处理"，数据量一大，后者明显更从容。

合并的时候还要考虑去重。真实数据里经常出现同一个 ID 在多个分片里重复的情况，用unique_by可以按字段去重，但它要求输入是数组，而且会改变元素顺序（内部会排序）。如果你需要保留原始顺序，就得用reduce手动维护一个已见集合：

jq -s ' reduce .[] as $item ({seen: {}, out: []}; if .seen[$item.order_id] then . else .seen[$item.order_id] = true | .out += [$item] end) | .out ' parts/*.json > dedup.json

这段写起来比unique_by啰嗦，但在"必须保序"的场景里是唯一可靠的办法。我第一次写的时候把.out += [$item]写成了.out + [$item]，结果每次迭代都返回新对象但没被后续引用，最终输出是个空数组——排查了二十分钟才反应过来，reduce的状态更新必须写成赋值形式。

4.3 场景三：批量改写字段并做字段裁剪（脱敏）

导出数据给外部使用时，手机号、邮箱、内部 ID 这类字段必须处理掉。jq 改字段的方式是"构造新对象"，而不是"就地修改"——jq 没有原地修改文件的能力，所有改写都是产生新值，你要自己重定向回文件（注意不要>到同一个文件，会先清空导致读不到内容，务必先写临时文件）。

# 删除敏感字段 + 对手机号做掩码 + 补充导出时间 jq ' del(.user.phone, .user.email) | .user.id = (.user.id | tostring | .[0:3] + "****") | .exported_at = (now | floor) ' order.json > order_safe.json

now返回的是带小数的秒级时间戳，floor取整去掉小数。如果你要的是可读时间，jq 1.6 提供了todate，但它输出的是 UTC 时间，想要本地时间还得自己处理时区偏移，这一点后面踩坑那节会细说。

批量改写的时候，用 shell 循环加临时文件是最稳的组合：

mkdir -p out for f in raw/*.json; do jq 'del(.user.phone)' "$f" > "out/$(basename "$f")" done

这段循环有三个值得注意的地方。第一，basename保住了原文件名，方便回溯；第二，重定向到不同目录，避免了覆盖源文件的风险；第三，如果某个文件解析失败，jq 会报错但循环会继续，最后你得到的是一个"部分成功"的目录——生产环境里我建议加上set -e或者在循环里判断退出码，把失败的文件名记下来单独重跑，而不是让半成品混在结果里。

5. 与其他命令行工具的协作边界

5.1 与 curl 的配合：接口数据一步到位

jq 最常见的搭档就是 curl。一个典型的组合是这样的：先看结构，再取字段，最后落盘。

# 第一步：看结构（只看前 20 行，避免刷屏） curl -s "https://example.internal/api/orders?page=1" | jq . | head -n 20 # 第二步：确认路径后直接取值 curl -s "https://example.internal/api/orders?page=1" \ | jq -r '.data.list[] | [.order_id, .status, .amount] | @tsv'

这里有两个协作层面的经验。一是curl -s关掉进度条，否则进度信息会混进管道污染 JSON；二是如果接口返回的响应体前面带了 BOM 或者多余的调试文本，jq 会直接报解析错误，这时候先用head -c 200看一眼原始字节，比盲目调 jq 参数有效得多。另外，分页接口批量拉取时，用--arg把页码传进过滤器比在 URL 里做字符串拼接更安全：

for p in 1 2 3; do curl -s "https://example.internal/api/orders?page=$p" \ | jq -c --arg p "$p" '.data.list[] | {page: $p, id: .order_id}' done > all_orders.ndjson

这里输出的是 NDJSON（每行一个独立 JSON），而不是一个大数组，原因是流式追加方便、单行损坏不影响其他行、后续处理也能一行一行读。这个格式在日志和批量导出场景里是我的默认选择，除非对方明确要求数组。

5.2 该交给 jq 的别交给 grep

我见过不少脚本用grep加正则去捞 JSON 里的字段值，短时间能用，长期一定会出问题。原因很直白：JSON 是结构化数据，同一段文本在不同层级可能出现多次，正则匹配到的是"文本位置"而不是"字段路径"。举个具体的例子，.user.id和.items[0].id在文本上都长成"id":10086这样，grep 根本分不清你要的是哪个。

判断标准很简单：只要目标是"某个路径下的值"，就用 jq；只有当目标是"整行文本里是否出现某段字符"时，才用 grep。同理，sed和awk适合处理行式文本、字段分隔明确的表格数据，不适合处理有嵌套层级的 JSON。真要混用，也应该是先用 jq 把 JSON 拍平成 TSV，再交给 awk 做数值统计——顺序反了，麻烦就来了。

# 正确分工：jq 负责结构与取值，awk 负责数值汇总 jq -r '.items[] | [.sku, .qty, .price] | @tsv' order.json \ | awk -F'\t' '{ sum += $2 * $3 } END { printf "总金额: %.2f\n", sum }'

6. 常见报错与排查速查

6.1 报错信息对照表

jq 的报错信息不算友好，但常见就那么几种。下面这张表是我从自己的排查记录里整理出来的，遇到报错先对一遍，能省掉大半时间。

用?做容错是个很实用的技巧：..加?可以让错误变成静默跳过而不是中断。但反过来也要警惕，过度使用?会让你看不到真实的数据问题，该报错的时候不报，最后错在更下游的地方。我的一般原则是：开发调试阶段不加?，让错误暴露；上线脚本里对可能缺失的路径加?或//兜底。

6.2 我踩过的坑与处理办法

第一个坑是//运算符的语义。它叫"替代运算符"，规则是"左边如果是 false 或 null，就取右边"，注意false也算空值。所以.paid // "未知"在paid为false的时候会输出"未知"，而不是false。这个行为在布尔字段上会直接导致判断错误，我第一次遇到时还以为数据被改了。正确的写法是先判断存在性再取默认值：

# 错误示范：false 会被吞掉 jq '.paid // "未知"' order.json # 正确写法：只处理 null jq 'if .paid == null then "未知" else .paid end' order.json

第二个坑是length作用在数字上。jq 里length对数字的定义是"绝对值"，所以echo '-5' | jq 'length'输出5。如果你在做数据统计时误把数字传进length，结果会莫名其妙地"变成正数"。统计数组长度的正确写法是先包一层：([.items[]] | length)。

第三个坑是时间戳。fromdateiso8601只认2024-08-15T10:23:41Z这种格式，带+08:00时区偏移会直接抛错。而绝大多数接口返回的时间恰恰是带偏移的。处理办法是把偏移部分替换掉再转换，或者干脆用strptime自己解析——但strptime的行为在不同平台上对%z的支持不一致，可移植性差，所以我更倾向于替换法：

jq -r '.created_at | sub("\\+08:00$"; "Z") | fromdateiso8601' order.json

第四个坑是--arg和--argjson用混。--arg k 1传进去的是字符串"1"，--argjson k 1传进去的是数字1。用字符串去做数值比较会静默失败，比如--arg min "100"然后.price > $min，比较的是数字和字符串，结果全为 false。这个错误特别隐蔽，因为不报错、不警告，只是结果不对。

第五个坑是处理中文时的编码。jq 默认输出保留原始 UTF-8 字节，但如果你在 Windows 的默认编码环境下重定向输出，写出来的文件可能是乱码。稳妥的做法是全程在 UTF-8 环境下操作，导出给表格软件时再决定要不要补 BOM。

7. 大文件与流式处理

7.1--stream与内存的关系

一份 2GB 的 JSON 数组，直接jq '.[]'会先把整个文件解析进内存，机器内存不够就是一句Killed。这时候要用--stream，它的工作方式是把整棵树拆成一条条"路径 + 叶子值"的流，边读边吐，内存占用跟文件大小基本脱钩。

# 输出形如 [["items",0,"sku"],"S-1001"] 的路径-值对 jq --stream '.' big.json | head -n 5

--stream的代价是输出结构变了，你不能再按原来的路径取值，需要自己从路径数组里判断。实际用法通常是先过滤出关心的路径，再重组：

# 从流里挑出所有 sku 的值，过滤掉结构结束标记 jq --stream 'select(.[0][-1] == "sku") | .[1]' big.json

判断结束标记的方法是看数组长度：--stream输出的每一项要么是[路径, 值]两元素，要么是[路径]一元素的"容器结束"标记。不处理这个差异，你会得到一堆null。

另一个降低内存的手段是-c配合逐行处理。如果数据本身是 NDJSON（每行一条），完全不需要-s，直接逐行跑过滤器就行，内存只跟单行大小有关：

jq -c 'select(.level == "error") | {ts: .ts, msg: .msg}' app.log.ndjson > errors.ndjson

7.2 什么时候不该用 jq

这句话说出来可能有点扫兴，但确实有必要：jq 不是万能的，有些活儿交给别的工具更合适。

一是超大规模的聚合统计。jq 的group_by、sort_by都要把数据读进内存再排序，几百 MB 还行，几个 GB 就开始吃紧了。这时候把 JSON 拍平成 TSV 交给命令行统计工具，或者干脆丢给数据库，效率高一个数量级。

二是复杂的嵌套重构。如果你需要做多层嵌套、条件分支很多的转换，jq 的表达式会写得非常长且难维护，这时候用 Python 之类的脚本语言写几十行代码，可读性和可调试性都更好。判断标准是：超过 15 行、需要加注释才能看懂的 jq 命令，就该考虑换语言了。

三是需要严格类型校验的场景。jq 是弱类型的，"1"和1在很多操作里会被悄悄转换，如果你需要做严格的模式校验（比如要求某字段必须是整数且在某个区间），用专门的校验工具或者带类型的解析库更靠谱。

四是文件需要原地修改。jq 只会输出到标准输出，所谓"就地修改"必须先写临时文件再改名。这一步如果写错（直接>到同一文件），源数据会被清空——我就干过这事，一份手写的配置被覆盖成零字节，只能从版本记录里找回来。后来我的习惯固定为：任何"就地修改"都先cp一份备份，用临时文件写入，确认内容无误后再 mv 覆盖。

cp config.json config.json.bak jq '.timeout = 30' config.json > config.tmp && mv config.tmp config.json

最后再分享一个我一直在用的小习惯：凡是能复用的 jq 过滤器，都写进文本文件里，用-f引用，而不是每次在命令行里敲。原因有两个，一是命令行里的引号转义太容易出错，尤其是带正则和插值的表达式；二是文件里的过滤器可以写注释、可以进版本库、可以给同事看。

# rules.jq 文件内容示例 # 提取错误日志并标准化字段 select(.level == "error") | {ts: .ts, code: .code, msg: (.msg | gsub("\\s+"; " "))}

jq -c -f rules.jq app.log.ndjson

gsub那一行是清理日志里的连续空白，避免导出后表格错位，这个细节不加的话，日志里带换行符的消息会把 CSV 直接撑坏——这也是我在实际导出时被坑过一次之后才补上的。