开发者工具 · JSON 格式化程序和验证程序
在 CI 之前修复损坏的 package.json：读取错误位置
· 为什么它很重要
json 开发人员工作流程 验证
手动编辑的 package.json、composer.json 或 launch.json 在保存后很长时间就会失败（通常在 CI 中）。这篇文章展示了如何在提交之前进行验证并快速读取错误位置。
十二分钟的管道来了解一个逗号
十二分钟的管道来了解一个逗号 - 手动解决合并冲突，绿色编辑器和红色构建。存储库签出看起来很正常，因为 Git 记录的是字节，而不是清单是否解析。然后 CI 安装依赖项、到达损坏的文件并在测试提供任何有用信号之前停止。
该工具仅检查严格的 JSON 语法，并接受最多 8,000,000 JavaScript 字符的文档。 package.json 和composer.json 是合适的严格示例。 tsconfig.json 等文件可能使用注释容忍解析器，因此拒绝它们的注释作为 JSON 并不能证明拥有工具会拒绝它们。根据使用程序实际声明的语法进行验证。
哪个 JSON 配置文件最常损坏
哪些 JSON 配置文件最常损坏 - package.json、composer.json、launch.json 和锁定文件，以及为什么允许注释的 tsconfig.json 需要单独处理。人工编辑的清单往往会因依赖块、脚本和嵌套工具设置而失败。生成的锁定文件会以不同的方式失败：手动解决冲突可能会损坏分隔符或重复的结构部分。
不要假设每个具有类似 JSON 扩展名的文件都使用严格的 JSON。 VS Code 设置和 TypeScript 配置通常允许通过专门的解析器进行注释或尾随逗号，而包清单通常不允许。尽可能使用包管理器验证生成的锁定文件，因为仅有效语法无法恢复该生成器所期望的哈希、排序规则或内部一致性。
为什么工具会迟到失败 - 包管理器和编译器按需解析，因此语法错误在安装或构建时而不是在保存时出现
为什么工具会迟到失败 - 包管理器和编译器按需解析，因此语法错误在安装或构建时而不是在保存时出现。文本编辑器可以在不运行权威解析器的情况下为大括号着色，并且在狭窄的本地任务期间可能无法读取更改的清单。 CI 从干净的环境开始，并练习缓存工作站跳过的设置路径。
由此产生的延迟包括排队时间、结帐时间、依赖关系设置和不相关的初步作业。更糟糕的是，最终的消息可能仅命名无效的包文件，而将原始行隐藏在命令输出后面。编辑后立即进行本地解析会破坏该反馈循环。它还将语法错误与后来需要不同调查的依赖关系解析或模式错误分开。
读取压力下的错误位置
在压力下读取错误位置 — 行和列、前一个标记以及产生无效 JSON 的三个合并冲突模式。标记的字符是不可能继续的地方，而不总是错误开始的地方。收盘报价可能会暴露较早的未转义报价；大括号可能会显示下一个属性之前缺少的逗号。
合并后，查找保留为纯文本的冲突标记、不使用逗号连接的重复成员块以及在选择一侧时删除的分隔符。检查报告位置之前的令牌并计算周围的容器边界。进行一次修复，重新运行验证并保留原始差异，因为解析器通常仅报告第一个障碍，而第二个独立冲突可能会保留在更远的位置。
工作示例：错误合并后的 package.json
工作示例：错误合并后的 package.json — 重复的依赖项块、缺少的逗号、验证器报告和修复。想象一下 `"scripts":{"test":"vitest"}` 紧随其后的是 `"dependencies":{"vite":"7.3.6"}`。第二个属性名称是解析器发现对象缺少分隔符的地方，尽管纠正逗号属于脚本对象之后。
插入该逗号并在格式化之前再次验证。如果合并还生成了两个 `dependencies` 键，则严格解析仍可能成功，因为语法上允许重复名称，但 JavaScript 解析仅保留后面的值。比较两个分支并合并预期的成员，而不是机械地删除块。语法修复和语义合并解析是连续的、不同的任务。
让验证成为一种习惯
让验证成为一种习惯 - 在提交之前粘贴，或验证您在 IDE 外部编辑的任何 JSON，无需帐户或插件。最好的触发因素是行为：每当解决冲突标记、移动大块或手动输入标点符号时，在暂存文件之前运行所属工具的检查或严格的解析器。
存储库可以通过预提交检查和清单范围内的 CI 作业自动执行相同的规则，但自动化应该补充即时反馈，而不是成为第一个解析器。将格式化与修复分开，以便差异显示有意义的字符。对于生成的文件，从源清单重新生成，而不是标准化手工编辑的输出，然后让生成器证明其自身的不变量。
这不包括什么
这不包括语义错误，例如错误的版本范围或未知字段，有效的 JSON 无法保护您免受这些错误的影响。包清单可以在命名不存在的脚本时进行解析，将依赖项放入错误的部分或使用意外解析的版本表达式。重复的键也可以通过语法检查，同时默默地替换较早的值。
使用包管理器验证、模式、安装测试并审查这些层。此检查也不能证明锁定文件与其清单匹配，也不能证明启动配置命名了已安装的调试器。如果实际格式是 JSONC 或其他方言，请使用其解析器，而不是仅仅为了满足严格的 JSON 而删除支持的语法。语法是最早的门，而不是完整的配置合约。
要点：语法检查需要几秒钟，失败的管道需要几分钟
要点：语法检查需要几秒钟的时间，失败的管道需要几分钟的时间 - 并且验证器的精确报告缩短了修复时间。在最终编辑的字节上运行它，从报告的行和列开始，然后检查前面的标记是否缺少分隔符或定界符。每次更正后重新验证，因为后来的错误最初可以被隐藏。
一旦严格的语法通过，返回给使用者：运行包管理器、编译器或编辑器特定的验证来理解允许的字段和值。保持修复差异较小，尤其是在合并之后，以便审阅者可以区分标点符号和依赖性决策。此序列在本地捕获最便宜的故障，并为只有完整环境才能评估的行为保留昂贵的管道时间。