JSONC-带注释的 JSON 详解

你肯定用过 JSON，可能用在了配置文件、API 数据、项目里的各种设置等等地方，JSON 简洁、清晰，人和机器都爱读。但用多了，你是不是也遇到过这种抓狂的情况？

比如，你接手了一个新项目，打开 config.json，里面有一堆参数：

json 复制代码

{
  "maxRetries": 3,
  "timeoutMs": 5000,
  "featureFlagX": true,
  "legacyMode": false
}

看起来挺明白，对吧？但问题来了："featureFlagX 到底是干啥的？为啥要设成 true？这个 legacyMode 关了会不会导致系统老系统炸掉？" 没人告诉你，文档可能就没更新过，或者压根就没有。

这时候，你是不是特别想直接在 JSON 文件里写一行注释：

jsonc 复制代码

{
  // 这个功能还在灰度测试，别乱动！
  "featureFlagX": true,
  /* 
    警告：legacyMode 必须为 false，
    否则会触发 2018 年那个著名的内存泄漏 bug。
  */
  "legacyMode": false
}

想法很美好，但现实很骨感。

标准的 JSON 规范非常严格：不支持任何注释 。多一个空格都可能报错，更别说 // 或 /* */ 了。如果你硬塞进去，大部分标准的 JSON 解析器------比如浏览器的 JSON.parse()，或者很多后端库------会直接给你一个大大的错误，告诉你"这玩意儿不是 JSON"。

那大家怎么办？

聪明的开发者们当然不会坐以待毙。既然官方不让，那就自己搞一套呗！于是，"JSON with Comments"，简称 JSONC，就这么在民间流行开来了。

JSONC 的核心思想很简单：在开发阶段，我们用带注释的 JSON 来写配置，方便人类理解；但在程序真正运行前，先把它"净化"成标准的、不含注释的 JSON，再喂给解析器。

谁在用？

你可能不知不觉已经用上了。最著名的例子就是 Visual Studio Code 。打开你的 settings.json 或者 tasks.json，你会发现微软大方地允许你写 // 注释。VS Code 内部有个专门的解析器（叫 jsonc-parser），它能聪明地忽略掉这些注释，只提取真正的数据结构。TypeScript 的编译配置文件 tsconfig.json 也一样。

怎么玩起来？

如果你想在自己的项目里用 JSONC，关键在于工具链。你需要确保：

编辑器友好：你的代码编辑器（比如 VS Code, WebStorm）能高亮显示 JSONC，并且语法提示正常工作。好消息是，主流编辑器基本都支持。
有合适的解析器 ：你的程序不能直接用 JSON.parse()。你需要引入一个能处理注释的 JSONC 解析库。不同语言都有：
- JavaScript/Node.js : jsonc-parser (VS Code 用的那个), strip-json-comments
- Python : pyjson5 (JSON5 是 JSONC 的超集，功能更多), commentjson
- Go : github.com/tailscale/hujson
- Rust : json5 crate

用法通常也很简单。比如在 Node.js 里用 strip-json-comments：

javascript 复制代码

const fs = require('fs');
const stripJsonComments = require('strip-json-comments');

// 读取带注释的 JSONC 文件
const jsoncContent = fs.readFileSync('my-config.jsonc', 'utf8');
// 先剥离注释
const cleanJson = stripJsonComments(jsoncContent);
// 再用标准 JSON 解析
const config = JSON.parse(cleanJson);

值不值得用？

这得看场景。

强烈推荐用于配置文件：尤其是那些需要长期维护、多人协作、或者参数含义不那么直观的配置。一条好的注释能省下无数沟通成本和踩坑时间。VS Code 和 TypeScript 的成功实践就是最好的证明。
绝对不要用于数据交换 ：如果你的 API 要返回数据给外部系统，或者接收外部系统的数据，必须用标准 JSON。你不能指望别人的系统装了你的 JSONC 解析器。这时候注释的需求，应该通过完善的 API 文档来解决。

最后的小提醒

虽然 JSONC 很香，但记得在项目里明确约定好：

用什么扩展名？.jsonc 是个不错的选择，能清晰区分。
团队里所有人都知道这个文件需要特殊解析，不能直接 JSON.parse()。
如果项目依赖里没加解析库，千万别手痒直接提交带注释的 .json 文件到生产环境，那绝对是埋雷。

说到底，JSONC 不是什么黑科技，就是开发者为了对抗"配置即天书"这个痛点，自发形成的一个小默契。让冰冷的配置文件多了一点人情味，也让我们的工作少了一点无谓的猜测。只要用对地方，就是个称手的好工具。