带注释的 JSON

JSONC（带注释的 JSON）扩展了标准 JSON 以允许 JavaScript 风格的注释。许多开发工具使用 JSONC 作为配置文件格式，其中注释有助于记录设置。此解析器在保留数据结构的同时剥离注释以生成有效的 JSON。

规范

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

常见用例

• 为 TypeScript/JavaScript 项目解析 tsconfig.json 和 jsconfig.json
• 读取 VS Code settings.json 和扩展配置
• 处理 Cloudflare wrangler.jsonc 配置文件
• 编辑带有行内文档的 ESLint、Prettier 和其他工具配置

功能

• 解析单行注释（// comment）
• 解析多行注释（/* comment */）
• 处理尾随逗号（JSONC 文件中常见）
• 剥离注释以生成有效的 JSON 输出
• 所有标准 JSON 解析器功能（树视图、转换）

示例

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

提示

• VS Code、TypeScript 和许多现代工具原生支持 JSONC。
• 分享配置时，考虑接收者的工具是否支持注释。
• 当工具要求严格 JSON 时，通过剥离注释转换为标准 JSON。

理解 带注释的 JSON

JSONC（带注释的 JSON）是标准 JSON 的扩展，允许 JavaScript 风格的单行（//）和多行（/* */）注释，以及数组和对象中最后一个元素后的尾随逗号。虽然不是官方标准，但 JSONC 已成为面向开发者的配置文件的事实标准格式，行内文档能提高可维护性。

微软通过 Visual Studio Code 推广了 JSONC，VS Code 将其用于 settings.json、keybindings.json、launch.json 和 extensions.json。TypeScript 的 tsconfig.json 和 JavaScript 的 jsconfig.json 是 JSONC 文件，使用 .json 扩展名时的许多 ESLint、Prettier 和 Babel 配置文件也是如此。Cloudflare 的 wrangler.jsonc 明确使用 .jsonc 扩展名来表示支持注释。

JSONC 相比纯 JSON 的关键优势是文档记录。配置文件通常包含的设置其用途仅从键名来看并不明显。注释允许开发者解释设置存在的原因、有效值是什么以及更改的后果可能是什么。尾随逗号减少了版本控制的噪音，允许最后一个元素与所有其他元素具有相同的格式，因此添加新项目在 diff 中只显示一行更改而不是两行。

在底层，JSONC 解析器通过剥离注释和尾随逗号，然后将结果传递给标准 JSON 解析器来工作。这意味着数据模型与 JSON 相同——注释是给人类的元数据，不是给程序的数据。将 JSONC 转换为需要严格 JSON 合规性的工具使用的 JSON 时，只需移除注释。微软的 node-jsonc-parser 库（用于 VS Code）是 JSONC 解析的参考实现。

JSONC 不是由任何 RFC 或 ECMA 规范定义的官方标准。它是微软通过 VS Code 和 TypeScript 推广的惯例，其行为由作为参考实现的 jsonc-parser 库明确定义。其他支持 JSONC 的工具——ESLint、Prettier 和各种编辑器——遵循相同的单行注释、多行注释和尾随逗号惯例。常见的 JSONC 文件包括 tsconfig.json 和 jsconfig.json（TypeScript/JavaScript）、VS Code 设置文件（settings.json、launch.json、tasks.json、keybindings.json）、wrangler.jsonc（Cloudflare Workers）、devcontainer.json（VS Code Dev Containers）以及其他各种工具配置。任何主要由开发者编辑且可能受益于注释的 JSON 文件都可能支持 JSONC。

JSONC 只应用于由具有明确 JSONC 支持的工具读取的配置文件。API 响应、数据存储和服务间通信应始终使用标准 JSON，因为大多数 JSON 解析器会将注释视为语法错误而拒绝。要使用标准 JSON 解析器编程处理 JSONC 配置文件，请先使用支持 JSONC 的库剥离注释。

JSONC 比 JSON5 更保守，后者是 JSON 的一个更广泛的超集。JSONC 只添加了注释和尾随逗号，而 JSON5 还允许单引号字符串、不带引号的对象键、十六进制数字、前导和尾随小数点、Infinity 和 NaN 以及多行字符串。JSONC 在开发者生态系统中有更广泛的工具支持，而 JSON5 用于特定的配置文件如 Babel 的 babel.config.json5，但整体采用率更窄。