VS Code自动修复JSON格式错误：从格式化到一键修复的完整指南

下午三点，我在改一份从技术交流群里转来的配置型 JSON，刚把网址替换成自己的订阅地址，保存后整个文件就红了。鼠标悬停在第一行红色波浪线上，提示是 Expected double-quoted property name in JSON at position 2137。我习惯性地按了 Shift+Alt+F 格式化，波浪线纹丝不动，再用 JSON Tools 里的 Fix JSON 点了一下，红色波浪线直接消失。

这不是我第一次被 JSON 折磨。写得多了你会发现，VS Code 默认能力只解决了一半问题——它能及时告诉你“哪里不对”，但不会主动帮你改。这篇就围绕 VS Code 自动修复 JSON 格式错误这件事，把工具选型、实操链路、批量场景和踩坑经验一次说清楚。无论是新手还是老手，只要经常和 JSON 打交道，这篇都值得花十分钟看完。

1. “格式化并不等于修复”——VS Code默认对JSON做了什么

1.1 格式化只动排版，不碰语义

很多人一看到 JSON 报错，第一反应就是按格式化快捷键。实际上，Format Document 做的事情非常有限：重新排列缩进、换行、空格，把文件整理成好看的结构，仅此而已。它不会去删除一个多余的逗号，也不会帮你把漏掉的右括号补上。

用一个生活化的类比来解释：格式化相当于 Word 里的“自动排版”，它可以把文章段落对齐、字体调统一，但不会改正文章里的错别字。JSON 的语法错误就是错别字，排版再整齐，错别字还是错别字。

更关键的是，格式化还有个前提——文件必须能被解析器读进去。如果 JSON 文件已经损坏到语法层面，比如缺少右括号，Prettier 这类格式化工具往往会直接拒绝工作，连排版的力气都不出。所以你会看到一种尴尬现象：文件爆红了，按格式化没反应，但 Problems 面板里的错误还挂着。

VS Code 内置的 JSON 校验是实时、底层的。它本质上调用了一个 JSON 解析器去读文件内容，一旦读到不合法语法，立刻在 Problems 面板报错。这个校验能力非常强大，但校验和修复是两码事，它只负责“发现问题”，不负责“解决问题”。

1.2 JSON解析器的报错位置为什么总在“奇怪的地方”

我见过不少新手被 JSON 解析器的报错位置搞崩溃过。明明脏乱差的地方在第 10 行，VS Code 却把红色波浪线画在了文件末尾第 500 行附近，提示 Unexpected token } in JSON at position 12345。

这不是 VS Code 的 bug，而是 JSON 解析器的天然特性。JSON 解析是从左到右逐字符扫描的流式过程，解析器在处理一个结构时，如果内部已经收敛到一个完整状态，它会继续期待下一个 token。比如一个对象后面多了一个逗号，解析器读完最后一个键值对后，已经准备接受右边括号了，结果等来一个逗号，它并不知道这个逗号属于哪个位置，只能把“意外 token”扔在当前匹配状态附近。也就是说，报错位置是“当前解析状态”，不一定是“真实错误位置”。

最典型就是尾逗号问题：

json复制{
  "a": 1,
  "b": 2,
}

解析器读完 "b": 2 后，发现直接遇到了 }，它认为对象结构合法结束了，然后下一个 token 才是真正的 }，这时才报“多余右括号”。对于大型嵌套 JSON 文件，这个错位会让你在错误的位置翻来覆去找很久。

1.3 VS Code能实时校验，但缺一步“语义修复”

总结一下 VS Code 自带能力的天花板：

• 能做：JSON 语法实时校验、Problems 面板展示错误、缩放、括号跳转、HTML/JSON/JSONC 语言模式切换、基础格式化。
• 不能做：自动删除尾逗号、自动补全缺失引号、自动把中文引号转成英文引号、自动移除 JSON5 风格的单引号和注释。

这些“不能做”的恰恰是日常最痛的场景。社区分享的配置型 JSON 文件，经常带着尾逗号、注释、单引号、裸键名，甚至混入中文符号。VS Code 只会报一堆红色错误，但修复要你手动来。

于是问题就变成了：怎么让 VS Code 自动完成这些修复动作？答案是装插件。

2. 让VS Code真正具备“自动修复”能力的工具组合

2.1 JSON Tools：一键修复JSON的实用插件

先说我最推荐的工具：JSON Tools 扩展。在扩展商店搜索 JSON Tools（作者是 terrythen）安装即可。它的核心能力是多种 JSON 操作，其中对格式错误处理最直接的是 Fix JSON 功能。

Fix JSON 的适用场景非常暴力：

• 移除尾逗号
• 把单引号属性名和单引号字符串转成双引号
• 自动给裸属性名加双引号
• 去掉 JSON5 风格的注释
• 修复中英文引号混用问题

使用方法有两种：

1. 右键点击 JSON 文档，在菜单中选择 “JSON Tools -> Fix JSON”。
2. 打开 Command Palette（Ctrl+Shift+P），输入 Fix JSON 回车。

修复完成后，Fix JSON 会重写整个文件，把不标准的 JSON 内容转换为标准 JSON。文件会立即脱离爆红状态。我经常用这个功能处理从群聊或论坛下载的配置文件，效果立竿见影。

除了 Fix，JSON Tools 还提供 Sort JSON（按键排序）、Minify JSON（压缩为单行）、Analyze JSON（分析结构）、Copy JSON Path 等操作。Analyze JSON 对于排查大文件特别有用，可以快速知道 JSON 的根类型、键数量、最深嵌套层级，减少肉眼寻找的时间。

2.2 Prettier：格式化的默认搭档与onSave配置

Prettier 是另一大类工具里最常用的一个。它的定位是格式化，不是修复语法。但它的价值在于，可以配置成保存时自动格式化，并提供严格的 JSON 书写规范（比如不带尾逗号、缩进统一、行宽换行）。

Prettier 对 JSON 的处理逻辑是：如果文件语法不合法，它会拒绝格式化并报错；如果语法合法，它会在保存时强制调整格式。也就是说，Prettier 更像“守门员”，而 JSON Tools 是“清洁工”。

我推荐两个组合使用而不是二选一。JSON Tools 负责把坏文件修复成合法 JSON，Prettier 负责在后续编辑过程中保持格式一致。顺序很明确：先 Fix，再 Format，最后 Save。

Prettier 在 settings.json 中的典型配置如下：

json复制{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.quickSuggestions": {
      "strings": true
    }
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

formatOnSave 会在保存时自动格式化，defaultFormatter 指定 JSON/JSONC 文件默认使用 Prettier。editor.quickSuggestions 中的 strings 设为 true，可以在字符串内部也触发补全提示，对写 JSON 配置文件挺友好。

2.3 其他备选方案：JSON5、ESLint与内置语言模式

不是所有人都愿意装两个插件。再列几个替代方案，每个适合的场景不同：

JSON5 扩展特别适合读那些“别人写的带注释 JSON”，但要小心：它只改变了编辑器的解析方式，不会把文件转换成标准 JSON。如果你要继续把它交给需要标准 JSON 的下游工具，还是得靠 Fix JSON 输出标准格式。

ESLint 的方案配置成本偏高，但对团队协作场景有价值。它能发现重复键，这在 JSON Tools 里是不会管的，后面会专门聊这个问题。

2.4 在Linux/Windows/macOS下设置配置文件的路径

很多人在问 Linux 下 VS Code 用户级全局配置文件的默认路径。在 Linux 上，用户级 settings.json 位于：

code复制~/.config/Code/User/settings.json

Windows 上则是：

code复制%APPDATA%\Code\User\settings.json

macOS 上在：

code复制~/Library/Application Support/Code/User/settings.json

听起来是小事，但装插件、配快捷键的时候经常需要手工编辑这个文件。我建议直接把上述路径加个书签，需要的时候秒开。

3. 一次真实JSON报错的完整修复链路

3.1 错误类型识别表：从报错信息到根因

为了让自动修复更有针对性，先建立报错信息与根因的对应关系。下面是日常工作中最常见的几类错误以及修复手段：

注意第四类：Illegal token <。很多时候是把网页源代码保存成了 .json，或者 JSON 文件里混入了一行 <!-- json config code number --> 之类的 HTML 注释。这种不是格式修复能解决的，你得先看文件内容本身是否选错了文件。VS Code 能自动修复的是“JSON 语法层面的错误”，不是“内容完全不是 JSON”的情况。

3.2 用JSON Tools一键修复的实操过程

直接跑一个带问题的例子。假设某个配置文件长这样：

json复制{
  'name': 'tsconfig',
  'include': ['src/**/*',],
  'compilerOptions': { "strict": true,, }
}

这个文件有四个问题：单引号键名、单引号字符串、尾逗号、连续两个逗号。VS Code 会在多处爆红。我做的操作是：

1. 先打开 Problems 面板（Ctrl+Shift+M），快速浏览报错数量，这会让我心里有数——如果没有报错就说明文件已经是合法 JSON。
2. 右键点击编辑器任意位置，选择 JSON Tools -> Fix JSON。
3. 修复完成后，再按 Shift+Alt+F 格式化。
4. 保存，然后看 git diff，确认修复后的内容和原始内容只有格式差异。

修复后的效果：

json复制{
  "name": "tsconfig",
  "include": ["src/**/*"],
  "compilerOptions": {
    "strict": true
  }
}

整个过程不到五秒。对比手动去定位每一个引号和逗号，效率提升非常明显。

3.3 报错位置偏移案例：尾逗号与括号配对

前面说了报错位置可能和真实错误位置不一致，这里放一个真实案例。文件内容如下：

json复制{
  "items": [
    {"id": 1, "name": "a"},
    {"id": 2, "name": "b"},
  ],
  "total": 2,
}

VS Code 的报错位置通常出现在文件末尾，因为解析器解析完 "total": 2 之后，认为整个对象结构已经闭合，多余的 } 就成了意外 token。但如果你的实际文件有几百行，光标定位到末尾，根本找不到问题在哪里。

另一个更隐蔽的骗局是中文引号。比如把 "name": "书源" 写成了 "name": “书源”，解析器把它当成普通字符串内容的一部分，后面所有字符串都开始错位，直到文件末尾无法闭合才报错。这种时候就算盯着报错位置拆解半天也没用。

解决办法很简单：不要试图在报错位置上死磕，直接按 JSON Tools 的 Fix JSON，大部分这类问题会一次性解决。

4. 自动修复的边界与进阶场景：从单个文件到批量处理

4.1 JSONC与JSON5：非标准JSON的宽容解析

先解释两个概念：JSONC 即 JSON with Comments，VS Code 内置支持，常用于 settings.json、tasks.json 这类编辑器配置文件，允许注释和尾逗号；JSON5 是 JSON 的宽松超集，支持单引号、裸键、注释、尾逗号、十六进制数等。

想处理带注释的 JSON，最简单的方法是直接把文件扩展名改为 .jsonc，VS Code 就不会报错。但这有个前提：下游工具要能接受 JSONC。如果你要把文件交给一个严格 JSON 解析器，就得在交付前去掉注释。

JSON5 扩展的价值在于，当你确实需要阅读和编辑一个风格奔放的 JSON5 文件时，VS Code 的校验器不会充满红色波浪线。但注意，JSON5 扩展不会把文件转成标准 JSON。真正的转换还是要靠 JSON Tools 的 Fix JSON 或者脚本。

给一个实操建议：如果文件是别人分享的配置型 JSON，后缀是 .json，但里面充满注释和单引号，先用 JSON Tools Fix 一次，再手动确认数据内容，一般就能稳定使用了。

4.2 批量修复大量损坏JSON的Node.js脚本

单个文件用插件修复很方便，但当你面对一个项目目录里的几十个 JSON 文件时，一个个打开点 Fix 太不现实。批量场景我会直接用 Node.js 写一个零依赖的修复脚本，核心思路是：先尝试标准 JSON.parse，失败后用 JSON5 的宽容解析器解析，再序列化为标准 JSON 写回文件。

javascript复制const fs = require('fs');
const path = require('path');
const JSON5 = require('json5');

function fixJsonFile(filePath) {
  const raw = fs.readFileSync(filePath, 'utf8');

  try {
    JSON.parse(raw);
    console.log(`OK: ${filePath}`);
  } catch (e) {
    try {
      const obj = JSON5.parse(raw);
      fs.writeFileSync(filePath, JSON.stringify(obj, null, 2), 'utf8');
      console.log(`FIXED: ${filePath}`);
    } catch (e2) {
      console.error(`FAIL: ${filePath} => ${e2.message}`);
    }
  }
}

function walk(dir) {
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      walk(fullPath);
    } else if (entry.name.endsWith('.json')) {
      fixJsonFile(fullPath);
    }
  }
}

walk('./data');

使用前先 npm install json5，然后 node fix-json.js。脚本会列出每个文件的处理状态：OK 表示本来就是合法 JSON，FIXED 表示已被修复，FAIL 表示修复失败需要人工介入。

这个脚本处理尾逗号、单引号、注释类问题非常稳定，但遇到文件里混入 HTML 或者二进制内容时依然会 FAIL，这是正常的，因为那种情况根本不是 JSON 层面的问题。

4.3 配置型JSON的典型场景：书源、日历数据、标注文件、DataX参数

批量修复脚本在我手里的高频使用场景有这么几类：

第一类是社区分享的配置型 JSON，比如阅读器书源、音乐源、订阅源。这类 JSON 经常来自群聊或论坛，手工编辑痕迹非常重，尾逗号、注释、中文引号是常态。VS Code 打开后一片红，Fix 一遍基本就能给客户端导入使用。

第二类是自动化生成的 JSON 数据文件，比如 2026 年日历数据 JSON、节假日数据、汇率数据。这类文件数据量很大，往往在某个数据项后多了一个逗号，导致整个文件无法解析。单个文件用 JSON Tools 修，批量文件用脚本扫一遍，效率最高。

第三类是图像分割任务使用的标注文件（COCO 格式 JSON）。标注文件对结构的严格性要求极高，字段类型、数组嵌套、类别 ID 对应关系都不能出错。如果标注过程中某个文件写坏了，VS Code 的 Analyze JSON 能帮你快速看出根类型是什么、嵌套层级够不够；再配合 JSON Tools 修复，能挽回不少标注进度。

第四类是数据集成工具的任务配置，比如 DataX 的 JSON 参数文件。手写 DataX 配置时很容易把数组和对象嵌套写错，Fix JSON 能解决括号和引号问题，但业务字段的逻辑错误还得你自己去对文档。JSON 格式修复解决的是“能不能解析”，而“解析出来对不对”永远需要人来判断。

4.4 修复后的校验与转换

修复完一个 JSON 文件，不能只看编辑器不报红就认为万事大吉，建议再做一次命令行校验。

在终端里最简单的方式：

bash复制jq empty yourfile.json

如果文件合法，命令不会有任何输出；非法的话 jq 会直接报错并指出位置。这个命令在 CI 脚本里也很适合作为校验步骤。

另一个常用校验方式：

bash复制python -m json.tool yourfile.json

它会把 JSON 格式化后输出，非法 JSON 则抛出异常。对 Python 环境熟悉的朋友可以直接用这个。

完成校验后，如果还需要把 JSON 转成 YAML、XML、CSV 等格式，一定要在标准 JSON 的前提下做转换。先用 Fix JSON 修复，再转换，能避免原始错误被带入下一个格式，造成链式污染。

5. 用了这么久之后的避坑心得与工作流设置

5.1 一键修复不等于语义正确，修复前先留备份

JSON Tools 的 Fix JSON 很强大，但它解决的是语法层面问题，不是语义层面问题。重复键、字段类型错误、数字精度丢失、结构表达不符合业务预期，它统统不管。

最典型的问题是重复键。JSON 标准允许重复键，但后一个值会覆盖前一个值。Fix JSON 不会把重复键当成错误处理，但如果你在修复一个语言包文件，重复键可能导致界面文本被错误覆盖。这种事在代码评审里很难发现，因为它不报错。

所以我给自己立了一条规矩：在修复不可控的外部 JSON 文件前，先复制一份备份，或者确保当前改动已经在 Git 里可见。修复后认真看 diff，确认修复工具没有把某些奇怪内容改坏。尤其是从论坛下载的书源、接口配置这种文件，里面可能存在大量重复键或非预期数据，直接 Fix 并覆盖原文件是一种危险行为。

5.2 行尾序列、编码和BOM问题

Windows 和 Linux 开发者的 JSON 文件行尾序列不一致是非常常见的坑。VS Code 默认在 Windows 上新建文件可能是 CRLF，而在 Linux 服务器上跑的解析器没问题，但某些严格的校验工具或 Docker 容器里的脚本可能因为 \r 导致解析异常。

解决办法是在 VS Code 右下角点击 CRLF 或 LF，选择 LF 并保存。也可以在 settings.json 里统一配置：

json复制{
  "files.eol": "\n"
}

还有一个经常被忽略的问题：UTF-8 with BOM。带 BOM 的 JSON 文件在部分解析器眼中，第一个字符不是 { 而是不可见控制字符，直接报错。VS Code 右下角编码按钮可以查看当前编码，如果保存成了 UTF-8 with BOM，可以在命令面板搜索 Save with Encoding，手动选择 UTF-8 去掉 BOM。

我的习惯是：JSON 文件一律 UTF-8 no BOM + LF，全项目统一。这个组合兼容性最好，Linux/Windows 通吃。

5.3 number超范围问题，别当格式错误处理

JSON 数字超范围不是格式错误，而是精度问题。JavaScript 的安全整数上限是 2^53 - 1，超过这个范围后，某些依赖 JS 数字类型的解析器会丢失精度。常见的触发场景是 13 位毫秒时间戳、雪花 ID、大整数订单号。

如果你在 VS Code 里看到一个 JSON 文件里有 1710000000000 这种数字，Fix JSON 不会报错，因为语法上完全合法。但下游 Java 或 Go 工具里如果把它解释成 Long，可能没问题；如果解释成 int，就会抛出“Number out of range”。所以这类问题不能靠编辑器修复，要从数据设计上解决：把这类长数字定义成字符串，或者在后端用对应的 64 位整数类型接收。

另外，如果你的 JSON 值里出现了超过 JS 安全范围的数字，而中间层用 Node.js 解析，建议在 JSON Schema 中把该字段定义为字符串，并在写入端就保证它是字符串。这个坑在接口对接时经常爆发，提前在 VS Code 里用搜索 [0-9]{16,} 扫一遍文件，能够提前发现隐患。

5.4 我建议的一套高效JSON工作流

最后分享我目前固定使用的一套工作流，结合了自动修复和手动确认，适合大多数人直接抄作业。

第一步，拿到任何外部 JSON 文件后，先用 JSON Tools 的 Fix JSON 修复一遍语法。这是所有后续操作的前提。

第二步，按 Shift+Alt+F 格式化，把结构整理清楚。

第三步，看 Problems 面板是否还有报错，有就继续修，没有就进入下一步。

第四步，用命令行的 jq empty 或 python -m json.tool 做一次校验，确保解析器层面没有隐藏问题。

第五步，如果文件是从外部导入的关键配置，一定用 Git 提交后再放业务环境里跑，避免修复过程意外改变了数据内容。

为了让第一步更快，我会给 JSON Tools 的 Fix 命令绑定一个快捷键。在 keybindings.json 里加上：

json复制{
  "key": "ctrl+alt+j",
  "command": "jsontools.fix",
  "when": "editorLangId == json || editorLangId == jsonc"
}

以后遇到 JSON 爆红，直接 Ctrl+Alt+J 一下，一秒完成修复。这个快捷键在我日常处理书源、订阅源和接口 Mock 数据时使用频率极高，比右键点击节省了不少时间。

踩过几次坑之后我最大的体会是：自动修复工具解决的是“语法灾难”，但真正的数据质量还是要靠校验和业务经验来兜底。工具用得好，能让你从手工寻找引号、逗号的低效劳动里解放出来，把精力花在更值得关注的业务逻辑上。