1. 为什么在 Ubuntu 上折腾 JSON 文件值得单独写一篇刚接触 Ubuntu 的朋友十个里有八个会在某个时刻遇到 JSON 文件。可能是配置某个开发工具时冒出来的settings.json可能是爬虫抓下来的一坨数据也可能是某个开源项目里必须手动改的package.json。这东西打开一看花括号套花括号引号冒号密密麻麻用默认的文本编辑器看两眼就头晕。更麻烦的是Ubuntu 自带的编辑器要么功能太弱要么对 JSON 的语法高亮和格式化支持不够友好改错一个逗号整个文件就废了。我在带新人的时候发现很多人卡在 JSON 上不是因为逻辑有多难而是因为工具没选对、方法没找对。明明三分钟能搞定的事硬是折腾了半小时。所以这篇内容就是把我自己这些年在这上面踩过的坑、试过的好用的方法一次性整理出来。不管你是刚装好 Ubuntu 的新手还是已经用了一段时间但还没找到顺手的 JSON 处理方式下面这三种方法总有一种适合你。核心关键词先摆出来Ubuntu、JSON、jq、Python、VS Code。这五个词基本覆盖了在 Ubuntu 上处理 JSON 的主流方案。我会从最轻量的命令行工具讲到图形化编辑器每种方法都说清楚适用场景、具体操作步骤、以及我实际用下来的感受。文章里涉及的命令和配置都可以直接复制粘贴使用不需要你额外去查文档。另外说一句JSON 本身并不复杂它就是一种结构化的数据格式你可以把它理解成一种“带标签的记事本”——每个数据都有一个名字键对应一个值。数组就是排好队的一串值对象就是一群键值对的集合。理解了这个后面不管用什么工具处理心里都有底。2. 方法一用 jq 在命令行里把 JSON 安排得明明白白2.1 jq 到底是什么为什么值得装jq 是一个专门处理 JSON 的命令行工具你可以把它想象成 JSON 界的sed和awk。它的核心能力是解析 JSON、提取字段、过滤数据、格式化输出、甚至做数学运算和字符串拼接。对于经常在终端里干活的人来说jq 几乎是必备工具。为什么我把它放在第一个讲因为它的安装成本极低使用门槛也不高而且一旦用顺手了效率比打开图形化编辑器快得多。比如你有一个几百行的 JSON 文件只想看其中某个字段的值用 jq 一行命令就出来了不用等编辑器加载也不用在密密麻麻的文本里用眼睛找。在 Ubuntu 上安装 jq 非常简单打开终端输入sudo apt update sudo apt install jq -y这两行命令做完jq 就装好了。验证一下jq --version如果输出类似jq-1.6或更高版本说明安装成功。这里有个小细节apt update这一步很多人会省略但如果你的软件源列表比较旧直接 install 可能会找不到包或者装到旧版本。花几秒钟更新一下省得后面出问题。2.2 jq 最常用的几个操作覆盖 80% 的日常需求装好之后先拿一个简单的 JSON 文件练手。假设你有一个data.json内容如下{ name: ubuntu-tool, version: 1.0.0, dependencies: { jq: ^1.6, python3: ^3.10 }, tags: [cli, json, linux] }格式化输出是整个文件最基础的用法jq . data.json这个命令会把压缩成一行的 JSON 展开成带缩进的易读格式。如果你拿到的 JSON 是从某个接口复制出来的所有内容挤在一行用这个命令瞬间就清爽了。提取特定字段是第二常用的操作jq .name data.json输出就是ubuntu-tool。注意这里输出带引号因为 jq 默认把字符串按 JSON 格式输出。如果你只想要纯文本加-r参数jq -r .name data.json输出就是ubuntu-tool没有引号。这个-r参数在写脚本的时候特别有用因为不带引号的字符串可以直接赋值给变量或者拼接到其他命令里。提取嵌套字段也很直观jq .dependencies.jq data.json输出^1.6。用点号一层层往下走跟访问对象属性的写法一样。处理数组的时候jq 的能力就更明显了。比如要取tags数组的第一个元素jq .tags[0] data.json输出cli。要取整个数组并展开成多行jq -r .tags[] data.json输出三行分别是cli、json、linux。这个[]的写法表示遍历数组所有元素在处理列表数据时非常实用。2.3 jq 进阶用法过滤、映射和管道组合当你熟悉了基础操作之后jq 真正的威力在于它可以像写小程序一样处理 JSON。比如你有一个数组里面是多个对象你想筛选出满足条件的那些jq .[] | select(.version 1.0) packages.json这个命令的意思是遍历数组每个元素选出version字段大于1.0的对象。select是 jq 的内置函数配合管道符|使用逻辑非常清晰。再比如你想把每个对象的name字段单独抽出来组成一个新数组jq [.[] | .name] packages.json外面加一对方括号就把所有结果收集成数组了。这种写法在数据转换场景里特别常见。还有一个我经常用的技巧用 jq 修改 JSON 并输出到新文件。比如要把version字段改成2.0.0jq .version 2.0.0 data.json data_new.json注意这里用了重定向把结果写到新文件里。不要直接覆盖原文件除非你确认改对了。我一般习惯先输出到新文件用diff对比一下确认无误再决定要不要替换原文件。注意jq 的赋值操作不会修改原文件它只是把修改后的结果输出到标准输出。所以你必须用重定向或者tee命令来保存结果。2.4 jq 实操中容易踩的坑第一个坑是中文编码问题。如果你的 JSON 文件里有中文而终端编码设置不对jq 输出可能会乱码。解决办法是确保LANG环境变量设置正确export LANGen_US.UTF-8或者直接在命令前加上LANGen_US.UTF-8 jq . data.json第二个坑是JSON 文件本身格式不合法。jq 对 JSON 语法要求很严格多一个逗号、少一个引号都会报错。报错信息通常会指出出错的行号和位置比如parse error: Expected separator between values at line 5。遇到这种情况先用 Python 的json.tool模块检查一下python3 -m json.tool data.json这个命令会尝试解析文件如果格式有问题会给出更详细的错误提示。确认格式没问题之后再用 jq 处理。第三个坑是jq 的版本差异。Ubuntu 不同版本自带的 jq 版本可能不一样一些较新的语法特性在旧版本上不支持。比如--argjson参数在很老的版本里就没有。如果你发现某个写法报错先查一下版本号必要时可以从官方渠道获取更新的版本。3. 方法二用 Python 脚本灵活处理 JSON 数据3.1 什么时候该用 Python 而不是 jqjq 虽然强大但它毕竟是一个命令行工具适合做“一次性”的提取和过滤。如果你需要做更复杂的逻辑处理比如根据多个字段计算一个新值、把 JSON 数据转换成其他格式、或者批量处理多个文件Python 就更合适了。Ubuntu 系统默认自带 Python3你可以直接打开终端输入python3进入交互环境。不需要额外安装任何东西这一点比 Windows 省心得多。先确认一下版本python3 --version只要输出是 Python 3.x 就没问题。如果提示找不到命令说明系统里没有预装用sudo apt install python3装一下即可。3.2 用 Python 读取和查看 JSON 文件Python 处理 JSON 的核心就是json模块它是标准库的一部分不需要 pip 安装。最基本的读取操作import json with open(data.json, r, encodingutf-8) as f: data json.load(f) print(data) print(type(data))这段代码做了几件事打开文件、用json.load()把文件内容解析成 Python 对象、打印出来看看类型。json.load()和json.loads()的区别要分清楚load是从文件对象读取loads是从字符串读取。新手最容易搞混这两个。解析之后data就是一个普通的 Python 字典或列表你可以用所有 Python 的语法来操作它。比如# 访问嵌套字段 print(data[dependencies][jq]) # 遍历数组 for tag in data[tags]: print(tag) # 条件判断 if data[version] 1.0.0: print(版本匹配)这种灵活性是 jq 比不了的。你可以写循环、写函数、引入其他模块做任何你想做的处理。3.3 用 Python 编辑和保存 JSON 文件修改 JSON 数据同样简单import json with open(data.json, r, encodingutf-8) as f: data json.load(f) # 修改字段 data[version] 2.0.0 data[dependencies][jq] ^1.7 # 添加新字段 data[description] 一个用于演示的 JSON 文件 # 写回文件 with open(data_new.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2)这里有几个关键点需要说明。ensure_asciiFalse是为了让中文正常显示如果不加这个参数中文会被转义成\uXXXX的形式虽然数据没错但看起来很难受。indent2是设置缩进为两个空格让输出的 JSON 文件格式美观。如果你想要四个空格缩进改成indent4就行。还有一个细节写文件时我用了data_new.json而不是直接覆盖data.json。这是一个好习惯尤其是在批量处理的时候保留原始文件可以在出错时快速回滚。3.4 Python 处理 JSON 的常见异常和排查方法用 Python 处理 JSON 最常遇到的错误就是json.decoder.JSONDecodeError。这个错误通常有几个原因文件里有注释。标准 JSON 不支持注释但很多人会习惯性加//或#导致解析失败。末尾多了逗号。比如{a: 1, b: 2,}这种写法在 JavaScript 里合法但在标准 JSON 里不合法。引号不匹配。JSON 要求键和字符串值必须用双引号单引号是不行的。文件编码问题。如果文件不是 UTF-8 编码读取时可能报错。排查的时候可以先用python3 -m json.tool检查文件格式它会给出具体的错误位置。如果文件很大可以用head -n 20 data.json先看前几行往往问题就出在开头。另一个常见问题是数据类型不符合预期。比如你以为某个字段是字符串结果它是数字你以为某个字段是数组结果它是对象。这种问题不会报错但会导致后续逻辑出错。我的习惯是在解析之后先打印一下关键字段的类型print(type(data[version])) print(type(data[tags]))确认类型正确之后再继续操作。这个习惯帮我省了很多调试时间。提示如果你需要处理非常大的 JSON 文件比如几百 MB直接用json.load()可能会占用大量内存。这种情况下可以考虑使用ijson库做流式解析或者用jq先做初步过滤再交给 Python 处理。4. 方法三用 VS Code 图形化编辑 JSON 文件4.1 VS Code 在 Ubuntu 上的安装方式不是所有人都喜欢在终端里敲命令图形化编辑器对新手更友好。VS Code 是目前最流行的代码编辑器之一对 JSON 的支持非常完善而且免费。在 Ubuntu 上安装 VS Code 有几种方式我推荐用官方提供的.deb包安装这样后续更新比较方便。先从官网下载.deb安装包然后用dpkg安装sudo dpkg -i code_*.deb sudo apt install -f第二行命令是用来修复依赖关系的因为dpkg不会自动处理依赖。如果你下载的是其他格式的包也可以用snap安装sudo snap install code --classic两种方式都可以看个人习惯。安装完成后在终端输入code就能启动或者在应用列表里找到图标点击打开。4.2 VS Code 编辑 JSON 的核心功能和快捷键打开一个 JSON 文件之后VS Code 会自动识别文件类型并启用语法高亮。键和值会用不同颜色区分括号会配对高亮一眼就能看出结构层次。这是纯文本编辑器比不了的。格式化文档是我用得最多的功能。快捷键是Ctrl Shift I或者右键菜单里选择“格式化文档”。它会把整个 JSON 文件按照标准缩进重新排版不管原来的格式有多乱一键就整齐了。这个功能背后用的是 VS Code 内置的 JSON 格式化器遵循标准 JSON 规范。折叠和展开也很实用。JSON 嵌套层级深的时候你可以点击行号旁边的箭头把某个对象或数组折叠起来只看你关心的部分。快捷键Ctrl Shift [和Ctrl Shift ]可以快速折叠和展开当前层级。查找和替换在 JSON 文件里同样好用。Ctrl F打开查找框输入关键词就能定位到所有匹配位置。如果要批量替换某个字段的值用Ctrl H打开替换框支持正则表达式处理大批量修改时效率很高。错误提示是 VS Code 的另一个强项。如果你的 JSON 格式有问题比如少了逗号或者引号不匹配VS Code 会在问题行下面画波浪线鼠标悬停上去会显示具体的错误信息。这比在终端里看报错信息直观多了。4.3 配合插件让 JSON 编辑体验再上一个台阶VS Code 本身对 JSON 的支持已经不错了但装几个插件能让体验更好。我常用的有这几个Prettier是一个代码格式化插件支持 JSON、JavaScript、CSS 等多种格式。装完之后可以设置保存时自动格式化这样你每次Ctrl S保存文件它都会自动帮你整理格式。配置方法是在设置里搜索format on save勾选即可。JSON Tools提供了一些额外的 JSON 操作比如压缩、转义、排序键等。有时候你需要把格式化的 JSON 压缩成一行用这个插件一键就能完成不用去命令行敲jq -c。Error Lens会把错误信息直接显示在代码行末尾不用鼠标悬停就能看到。对于 JSON 这种对语法要求严格的文件格式来说这个插件能帮你快速定位问题。安装插件的方法很简单点击左侧边栏的扩展图标搜索插件名称点击安装。装完之后可能需要重启 VS Code 才能生效。4.4 VS Code 编辑 JSON 的注意事项虽然 VS Code 很好用但有几个地方需要注意。第一自动保存功能建议开启但如果你在编辑重要的配置文件最好还是手动保存避免误操作导致文件被覆盖。第二JSON 文件不要用 VS Code 的“另存为”来改扩展名比如把.json改成.json.bak这样 VS Code 可能不再识别为 JSON 文件语法高亮和格式化功能会失效。正确的做法是复制一份再改内容。第三如果你编辑的是系统级的配置文件比如/etc目录下的 JSON 文件需要管理员权限。用 VS Code 打开时要用sudo code /path/to/file否则保存时会提示权限不足。但要注意用sudo启动 VS Code 可能会导致配置文件权限混乱更安全的做法是先用sudo cp把文件复制到用户目录编辑好之后再sudo cp回去。注意VS Code 默认的 JSON 格式化器对 JSONC带注释的 JSON也支持但标准 JSON 文件里不要加注释否则其他工具解析时会报错。5. 三种方法怎么选场景对照与组合使用建议5.1 不同场景下的工具选择对照表这三种方法没有绝对的好坏关键看场景。我整理了一个对照表方便你快速判断该用哪个场景推荐方法理由快速查看 JSON 文件结构jq一条命令搞定不用打开编辑器提取某个字段的值jq命令行直接输出方便管道传递批量处理多个 JSON 文件Python可以写循环和函数灵活度高复杂数据转换和计算Python支持完整编程逻辑手动编辑配置文件VS Code可视化操作有语法检查和格式化调试 JSON 格式错误VS Code PythonVS Code 直观定位Python 详细报错在服务器上无图形界面操作jq 或 Python不需要图形环境需要频繁修改和预览VS Code实时高亮和格式化体验最好这张表不是绝对的实际使用中经常组合。比如我经常用 jq 先过滤出需要的数据再用 Python 做进一步处理最后用 VS Code 检查结果。工具之间可以配合不用拘泥于一种。5.2 组合使用的实际案例举个我最近遇到的例子有一个包含几百个条目的 JSON 数组每个条目有name、version、status三个字段。我需要找出所有status为active且version大于1.0的条目把它们的name提取出来生成一个新的 JSON 文件。第一步用 jq 快速筛选jq [.[] | select(.status active and .version 1.0) | .name] input.json filtered.json这一步几秒钟就完成了如果用 Python 写脚本至少得写十几行代码。第二步用 Python 做进一步处理比如给每个 name 加上前缀import json with open(filtered.json, r) as f: names json.load(f) result [fpkg-{name} for name in names] with open(output.json, w) as f: json.dump(result, f, indent2)第三步用 VS Code 打开output.json检查结果是否正确。整个过程行云流水每种工具都发挥了自己最擅长的部分。5.3 新手容易陷入的误区第一个误区是试图用一种工具解决所有问题。有人觉得 jq 很酷就什么事都用 jq 做结果遇到复杂逻辑时写出来的 jq 表达式又长又难懂过两天自己都看不懂了。工具是为人服务的该换就换。第二个误区是忽视文件备份。不管用哪种方法编辑 JSON 文件动手之前先复制一份备份。我见过太多人直接改原文件改错了又没有备份只能从头再来。一条cp data.json data.json.bak的命令能省掉很多麻烦。第三个误区是不检查 JSON 格式就直接使用。有些人从网上复制一段 JSON 就直接往配置文件里粘贴结果格式有问题导致程序启动失败。养成习惯拿到 JSON 先用python3 -m json.tool或者 VS Code 检查一下格式确认无误再使用。6. 常见问题排查与实操避坑指南6.1 JSON 格式错误的快速定位方法JSON 格式错误是最常见的问题表现通常是程序报错说无法解析。快速定位的方法有几个方法一用 Python 的 json.tool 模块python3 -m json.tool data.json如果格式有问题它会输出类似这样的错误Expecting , delimiter: line 5 column 10 (char 87)直接告诉你第几行第几列出了问题非常精准。方法二用 jq 的解析功能jq . data.jsonjq 的报错信息也很详细会指出出错的位置和原因。方法三用 VS Code 打开VS Code 会在问题行下面画红色波浪线鼠标悬停就能看到错误描述。对于不熟悉命令行报错的新手来说这种方式最直观。6.2 中文乱码和编码问题的处理JSON 文件里的中文乱码通常是因为编码不一致。标准 JSON 推荐使用 UTF-8 编码但有些工具默认用其他编码保存文件导致读取时出现乱码。检查文件编码的方法file -i data.json输出会显示文件的编码格式比如charsetutf-8。如果不是 UTF-8可以用iconv转换iconv -f GBK -t UTF-8 data.json data_utf8.json用 Python 读取时明确指定编码with open(data.json, r, encodingutf-8) as f: data json.load(f)写入时同样指定with open(data.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2)ensure_asciiFalse这个参数一定要加否则中文会被转义成 Unicode 编码虽然数据没错但可读性很差。6.3 jq 命令报错“Cannot index array with string”怎么解决这个错误通常是因为你搞错了数据结构。比如你以为某个字段是对象用.field.subfield去访问但实际上它是数组应该用.field[0].subfield或者.field[].subfield。排查方法是先用jq type看看字段的类型jq .field | type data.json如果输出array说明是数组输出object说明是对象。确认类型之后再写对应的访问语法。另一个常见原因是 JSON 文件本身的结构和你以为的不一样。比如文件顶层是数组而不是对象那你用.name就会报错应该用.[0].name或者.[] | .name。遇到这种问题先用jq keys看看顶层有哪些键或者用jq type看看顶层类型。6.4 VS Code 保存 JSON 时提示权限不足的处理如果你编辑的是系统配置文件保存时可能会提示EACCES: permission denied。这是因为当前用户没有写入权限。解决方法有两种第一种是用sudo启动 VS Codesudo code /etc/config.json但这种方式有个副作用用sudo创建的文件所有者会变成 root后续用普通用户编辑时又会遇到权限问题。第二种方法更安全先把文件复制到用户目录编辑好之后再复制回去cp /etc/config.json ~/config.json code ~/config.json # 编辑完成后 sudo cp ~/config.json /etc/config.json这样既避免了权限问题又不会打乱系统文件的权限设置。我一般推荐第二种方法。6.5 常见问题速查表问题现象可能原因解决方法jq 报 parse errorJSON 格式不合法用python3 -m json.tool检查格式Python 报 JSONDecodeError文件有注释或末尾逗号移除注释和多余逗号中文显示为 \uXXXX未设置 ensure_asciiFalse写入时加ensure_asciiFalsejq 报 Cannot index array数据结构类型判断错误用jq type确认类型VS Code 保存提示权限不足文件属于 root 用户复制到用户目录编辑后再复制回去终端输出中文乱码编码设置不正确设置LANGen_US.UTF-8jq 命令找不到未安装 jqsudo apt install jq -yPython 找不到 json 模块Python 环境异常确认使用 python3 而非 python这张表里的问题基本覆盖了新手会遇到的 90% 的情况。遇到问题先查表大部分都能快速解决。7. 我个人的使用习惯和一些额外建议说了这么多方法最后分享一下我自己的使用习惯。日常工作中我大概 60% 的 JSON 操作是用 jq 完成的30% 用 Python10% 用 VS Code。jq 胜在快适合在终端里随手处理Python 胜在灵活适合写脚本和做复杂转换VS Code 胜在直观适合手动编辑配置文件和检查数据。对于刚接触 Ubuntu 的朋友我的建议是先把 jq 的基本用法学会这是投入产出比最高的。然后花点时间了解一下 Python 的 json 模块不需要学太深会读写和修改就够了。VS Code 可以等有图形界面需求的时候再装不用一开始就折腾。另外JSON 文件虽然简单但也有一些“潜规则”值得注意。比如键名最好用英文和数字避免特殊字符缩进统一用两个空格或四个空格不要混用文件末尾不要留多余的空行。这些细节不会导致程序报错但会影响文件的可读性和维护性。还有一个实用技巧如果你经常需要查看 JSON 文件可以在.bashrc里加一个别名alias jsonjq .这样以后直接输入json data.json就能格式化输出了少敲几个字符。类似的别名可以根据自己的习惯添加用起来很顺手。最后说一个我踩过的坑有一次我处理一个从接口获取的 JSON 文件用 jq 提取字段时一直报错检查了半天格式也没问题。后来发现是文件开头有一个看不见的 BOM 字符导致 jq 解析失败。解决办法是用sed去掉 BOMsed -i 1s/^\xEF\xBB\xBF// data.json这个问题不常见但遇到了会很头疼记下来以备不时之需。