用 jq 优雅地格式化剪贴板中的 JSON：一个跨平台技巧与容错方案

本文介绍如何用 jq 结合剪贴板工具（macOS 的 pbpaste/pbcopy 或 Linux 的 xclip），实现一键格式化剪贴板中的 JSON，并重点讨论了非 JSON 内容导致数据丢失的坑及对应的容错 alias 设计。

背景：jq 与剪贴板格式化

jq 是命令行下处理 JSON 数据的瑞士军刀，几乎所有接触过 JSON 数据的开发者都曾用它来过滤、映射、转换结构化数据。但很多时候，我们遇到的 JSON 并不在文件里，而是被我们从网页、API 文档或其他工具里复制到剪贴板中。此时频繁地手动创建临时文件、粘贴、格式化、再复制回来，实在繁琐。

Sequoia McDowell 在一篇关于 jq 技巧的文章中分享了一个极具启发性的用法——将剪贴板中的内容直接通过 jq 格式化并写回剪贴板，整个过程不落盘，零痕迹。这个思路看似简单，却极大提升了日常处理 JSON 的效率，尤其是在调试 API 响应、准备 Stack Overflow 提问或整理数据片段时。

原始技巧：macOS 下的别名

作者 Chris 在阅读该文时注意到了这样一个 snippet（原文针对 macOS 用户）：

bash
alias jsontidy="pbpaste | jq '.' | pbcopy"

这里 pbpaste 读取系统剪贴板文本，管道交给 jq '.'（jq '.' 表示将输入解析为 JSON 并原样打印，但会经过格式化处理，自动缩进为 2 空格），然后 pbcopy 将结果放回剪贴板。实际效果就是：复制一段 JSON 文本 → 执行 jsontidy → 粘帖得到的是美化后的 JSON。

这个 alias 之所以有用，是因为普遍开发者经常需要从浏览器、日志或其它来源复制 JSON，而原始文本可能是压缩成一行（minified）的，或者缩进混乱，直接阅读或分享不便。这个技巧让格式化和复制操作合二为一。

向 Linux 迁移：替换 pbpaste/pbcopy

Chris 首先指出了兼容性问题：pbpaste 与 pbcopy 是 macOS 专属工具。在 Linux 环境下，一般使用 xclip 或 xsel 来实现类似功能，其中 xclip 最常用。

对应 Linux 版本：

bash
alias jsontidy="xclip -selection clipboard -o | jq '.' | xclip -selection clipboard"

在该命令中：

• xclip -selection clipboard -o：从剪贴板读取内容，并输出到标准输出（-o 表示输出）。
• jq '.'：解析并格式化。
• xclip -selection clipboard：xclip 从标准输入获取文本，写入剪贴板（注意无选项时默认从标准输入读取）。

这里还需指出，不同 Linux 发行版对 xclip 的安装命名可能不同（如 Debian/Ubuntu 用 sudo apt install xclip），此外也要确保图形会话或 Wayland/X11 环境支持剪贴板。若使用 Wayland 原生协议，可能需改用 wl-clipboard 的 wl-copy/wl-paste，但一般开发者仍以 X11 兼容为主。

潜在 bug：非 JSON 输入会清空剪贴板

Chris 经验丰富，立刻嗅到上述 alias 的潜在风险。如果当前剪贴板内容不是合法 JSON 文本，jq 会解析失败并退出非零状态码（exit status 非 0），同时在 stderr 输出类似这样的错误信息：

parse error: Invalid numeric literal at line 1, column 6

而 stdout 中没有任何内容输出。但关键点是管道并不知道命令是否成功——管道串接只负责数据流转和进程退出码的传递，它不会因为中间某条命令失败而中断后续命令。因此 xclip -selection clipboard 仍会执行，从空的标准输入中得到空字符串，并将该空字符串写入剪贴板。这就导致用户的原始剪贴板内容被清空，而且丢失的数据无法恢复，因为剪贴板是覆盖式的。

这种情形一旦发生，第一反应可能是：我刚才复制了什么？糟糕，全没了。尤其是正在编辑文本或其他有价值内容时，这 bug 相当致命。

容错方案：利用 || 保留原文

Chris 提供了简洁而巧妙的修复方案：使用 shell 的逻辑或操作符 || 将格式化失败时的执行分支重定向为原样放回剪贴板。

alias jsontidy="xclip -selection clipboard -o | (jq '.' || xclip -selection clipboard -o) | xclip -selection clipboard"

拆解这条命令的流程：

1. 读取原始剪贴板内容，并传入管道。
2. 子 shell ( ... ) 中执行 jq '.' 命令。
3. 若 jq 成功（即内容合法 JSON），命令正常退出，其格式化后的输出会继续流向管道末端。
4. 若 jq 失败（返回非零），由于 || 存在，shell 会执行右侧命令 xclip -selection clipboard -o，它再次读取剪贴板（仍是原始内容，因为尚未写入），并将其输出到管道。
5. 管道末端那条 xclip -selection clipboard 接收到的内容，要么是格式化后的 JSON，要么是原始未变更的剪贴板内容，绝不会是空字符串。

这个方案的关键在于利用 || 在任何失败时自动对原始内容做了一个“转储”，相当于一个万无一失的 fallback。

注意实现细微差别：由于 || 的优先级低于管道（即 |）？事实上，shell 解析 a | b || c 时，会先将 a | b 作为一个整体，然后判断其退出状态，若失败则执行 c。因此这里刻意使用了子 shell 括号包裹，让 jq 的输出与 || 分支的输出都在同一管道中传递。如果不加括号，例如写做 xclip -selection clipboard -o | jq '.' || xclip -selection clipboard -o | xclip -selection clipboard，由于 || 优先级低于管道，会让三部分分成两组，结果大不相同——实际上 || 左侧是一个管道，右侧是另一个管道，根本达不到意想的效果。因此括号的加入是确保逻辑正确的重要细节，值得留意。

更深一层的优化思考

尽管上述容错方案在绝大多数场景下已经足够，但依然存在一些值得讨论的边界情况。

1. jq 对合法 JSON 也有失败情况

jq '.' 不仅仅会解析语法，还会执行表达式。对于极小概率的情况（例如输入内容超大，或包含特殊转义序列），jq 也可能因内存等资源错误而失败，而这类失败同样会触发 fallback，结果也达到了保留剪贴板的目的，是一种安全策略。

2. jq 默认输出会追加换行符，但仍会去除多余空格

jq '.' 的输出会规范地对数组和对象进行 2 空格缩进，并适当添加换行。由此可能改变原本完全合法的 JSON 文本格式——即不只是美化，而是规范化。如果用户希望保持原有格式不变，仅在必要时才格式化，那么这种副作用也许不是需要的。但通常这种规范化正是我们想要的。

3. 兼容 Windows？

若是在 Windows 上使用 PowerShell，也有对应的剪贴板命令 Get-Clipboard 与 Set-Clipboard，也可以用类似的思路。不过 Windows 上的 jq 不是内建工具，一般需下载 Windows 版可执行文件或利用包管理器（如 scoop/choco）安装。可能的设计为：

powershell
$clip = Get-Clipboard -Raw
$formatted = $clip | jq '.' 2>$null
if ($LASTEXITCODE -eq 0) { Set-Clipboard $formatted } else { Set-Clipboard $clip }

这里需要额外检查错误输出与退出码，因为 PowerShell 管道与原 shell 行为存在差异。但可以看出，思路在跨平台依然成立，只是实现细节不同。

4. 用 shell 函数替代 alias 以便传递参数

alias 的局限在于参数空间有限（比如可能希望 jq 不只输出原样格式，还带过滤或排序等）。此时可以定义一个更复杂的函数，并放置在 shell rc 文件（如 ~/.bashrc 或 ~/.zshrc）中：

bash
jsontidy() {
local input=$(xclip -selection clipboard -o)
local output
if output=$(echo "$input" | jq '.' 2>/dev/null); then
printf '%s' "$output" | xclip -selection clipboard
else
# 保留原始内容
printf '%s' "$input" | xclip -selection clipboard
fi
}

这种写法更灵活，也更易读和维护，适合对 BASH 有更深需求的用户。

现实意义与学习点

这个小技巧表面上只是把一个常见的终端操作简化成了一个 alias，但深挖下去却能发现许多 Unix 哲学的精髓：

• 管道组合单一功能的工具，实现强功能：剪贴板读取与写入、格式化、错误处理，全都是由多个基础命令巧妙串联完成。
• 理解管道与退出码的关系：管道并不会因为中间命令出错而阻断后续命令，所以一定要自己把控失败路径。
• 利用逻辑符进行优雅的 fallback：shell 的逻辑或可以作为便捷的默认值处理，但必须注意优先级与括号的运用。
• 命令工具的本土化适配：同样的逻辑在不同操作系统上换用不同的底层命令，体现出 Unix-like 环境的统一思想。

即使如 jq 这么常见的命令，其中也隐藏着不少设计细节。结合剪贴板这种“临时数据中转站”的场景，我们学会应该如何从他人 snippet 中提炼通用本质，并识别隐藏在简单表象下的边界条件。

结语

最后，Chris 在文章末尾将这段 alias 设计发布了出来，为在 Linux 与 macOS 上整日与 JSON 打交道的用户提供了一个现成且安全的便捷工具。只需要在 shell 配置中加入适当的 alias 定义，就能做到：无论剪贴板是否包含合法 JSON，都不会让它意外丢失内容，同时又能快速美化 JSON 数据。

这个示例还启发我们：越简单的工具，越要谨慎对待其“副作用”。任何 CLI 管道都有风险，尤其在涉及覆盖性写入（如剪贴板）时，要时刻意识到失败导致的数据损坏可能性。

原文链接：https://chris48s.github.io/blogmarks/posts/2021/jsontidy/