如何向 JSON 文件添加注释：标准限制、JSONC、JSON5 与兼容方案

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

先说结论：严格标准 JSON 不支持注释。在标准 JSON 文件中写入 // 或 /* ... */，严格解析器通常会报错。如果这是由 VS Code 或其他明确支持扩展语法的工具读取的配置文件，可以使用 JSONC 或 JSON5；如果文件要交给任意 JSON 程序、通过 API 传输或进行签名，则应保持严格 JSON。

标准 JSON 为什么不能写注释

JSON 的语法由 RFC 8259 和 ECMA-404 定义，标准 JSON 的媒体类型是 application/json。它允许空白、对象、数组、字符串、数字、布尔值和 null，但没有定义注释语法。

#	Preview	Product	Price
1		Dear Editor	$13.99	Buy on Amazon

因此，下面的内容不是标准 JSON：

{
  // 用户显示名称
  "name": "Alice"
}

{
  /* 用户显示名称 */
  "name": "Alice"
}

如果目标程序只接受标准 JSON，应删除注释：

{
  "name": "Alice"
}

文件名为 .json 并不能保证内容真的符合标准；真正决定能否读取的是使用它的程序及其解析器。

#1 Best Overall

Dear Editor

$13.99

Buy on Amazon

JSONC：为配置文件增加注释

JSONC（JSON with Comments）是广泛使用的 JSON 扩展格式，相关规范目前以草案形式维护。它在普通 JSON 语法基础上允许 JavaScript 风格的单行和多行注释，推荐使用 .jsonc 扩展名。

单行注释

{
  // 服务监听端口
  "port": 8080
}

也可以将注释放在值后面：

{
  "port": 8080 // 开发环境端口
}

但这只有在读取端支持 JSONC 时才有效。严格 JSON 解析器会在斜杠处报错。

多行注释

{
  /*
   * 数据库连接配置
   * 本地开发环境使用 localhost
   */
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

块注释以 /* 开始、以 */ 结束。JSONC 不支持嵌套块注释；漏写结束标记也会导致解析失败。注释不会成为解析后的数据。

JSONC 的几个边界

• JSONC 支持 // 和 /* ... */，不支持 # 注释。
• 尾随逗号不是 JSONC 的必需能力。参考实现默认不允许尾随逗号；某些 VS Code 配置环境可能接受它，但通常会显示警告。
• 不要因为编辑器能打开文件，就假设运行该文件的程序也支持 JSONC。

例如，下面的尾随逗号在严格 JSON 中一定无效，在 JSONC 环境中也不应默认认为安全：

{
  "name": "Alice",
}

在 VS Code 中编辑带注释的 JSON

VS Code 同时提供严格的 JSON 模式和 JSON with Comments（JSONC）模式。包括 settings.json、tasks.json 和 launch.json 在内的部分配置文件会按 JSONC 处理，因而可以使用注释。具体行为仍取决于配置文件的 Schema 和最终消费它的程序。参考官方 JSON 文档。

1. 在 VS Code 中打开文件。
2. 查看右下角的语言模式。如果显示 JSON，点击它。
3. 选择 JSON with Comments。
4. 加入 // 或 /* ... */ 注释。
5. 保存后，确认实际读取该文件的应用也支持 JSONC。

如果项目使用自定义扩展名，可以在 VS Code 的设置中关联到 JSONC：

{
  "files.associations": {
    "*.config.json": "jsonc"
  }
}

格式化文件可使用命令面板中的 Format Document，或使用快捷键：Windows 为 Shift+Alt+F，Linux 为 Ctrl+Shift+I，macOS 为 Shift+Option+F。

重要：切换 VS Code 的语言模式只改变编辑器的高亮、补全和校验方式，不会把文件转换成标准 JSON。

JSON5：比 JSONC 更宽松的选择

JSON5 是面向人工编写的 JSON 扩展。它支持单行和多行注释，还支持不加引号的合法标识符键名、单引号字符串和尾随逗号等语法。

{
  // JSON5 配置
  name: 'Alice',
  notifications: true,
}

JSON5 与 JSONC 不是同一种格式：

JSON5 文件可能包含严格 JSON 无法接受的语法。只有在应用明确使用 JSON5 解析器、团队也接受这些扩展时，才应选择 JSON5。不要把 JSON5 文件命名为 .json，否则其他工具会合理地认为它必须符合标准 JSON。

必须保持标准 JSON 时怎么办

把说明放到外部文档

如果文件需要被不同语言、第三方服务或公共 API 使用，最稳妥的方式是不写注释，把说明放在同目录的 Markdown 文档、README、API 文档、版本控制提交说明或应用内帮助中：

config/
  app.json
  README.md

外部文档特别适合记录配置项的用途、开发与生产环境差异、不可修改的字段以及环境变量覆盖规则。

使用 JSON Schema

如果需要描述字段类型、用途和约束，可以使用 JSON Schema：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "port": {
      "type": "integer",
      "description": "服务监听端口",
      "minimum": 1,
      "maximum": 65535,
      "$comment": "生产环境通常由部署系统覆盖"
    }
  }
}

description 面向使用 Schema 的工具和人，examples 用于示例，$comment 面向 Schema 的维护者。$comment 是 Schema 对象中的普通关键字，不是 JSON 实例文件的注释；它不会自动出现在被验证的数据中，Schema 实现也可以忽略或删除它。

增加正式字段，但要确认数据模型允许

{
  "host": "127.0.0.1",
  "port": 8080,
  "description": "本地开发服务器配置"
}

这里的 description 是真实数据，不是注释。随意加入 _comment 也一样：

{
  "_comment": "这是开发环境配置",
  "port": 8080
}

这种做法只有在应用明确规定该字段、Schema 允许它且下游不会将其当作业务数据时才合适。否则它可能污染 API 响应、签名、哈希、缓存或严格 Schema 校验。

写作阶段使用 JSONC，发布阶段生成 JSON

如果团队需要注释，但最终消费者只能接受标准 JSON，可以将带注释文件作为源文件：

config.jsonc
    ↓ JSONC 解析器
构建脚本去除注释并重新序列化
    ↓
config.json
    ↓
严格 JSON 消费者

不要用简单正则表达式删除注释。例如：

{
  "url": "https://example.com//path"
}

这里的 // 是字符串内容。如果直接删除“从 // 到行尾”的文本，就会破坏合法数据。

可靠流程是：

1. 使用能识别字符串、转义符和注释边界的 JSONC 或 JSON5 解析器。
2. 将源文件解析成数据结构。
3. 使用标准 JSON 序列化器重新输出。
4. 对生成文件执行严格 JSON 校验。
5. 在 CI 中验证发布产物，而不仅是编辑器中的源文件。

如果文件要签名、计算哈希或做规范化比较，应先生成严格 JSON，再对最终产物执行这些操作。

为什么 VS Code 能读注释，其他程序却不能

编辑器的语言模式与应用运行时解析器是两层不同的东西。VS Code 可能把某个配置文件交给 JSONC 解析逻辑，因此能高亮、补全和保存带注释的内容；运行程序却可能调用只实现标准 JSON 的解析器，并在第一个 / 处失败。

判断兼容性时，依次确认：

1. 谁负责读取文件；
2. 它使用严格 JSON、JSONC 还是 JSON5 解析器；
3. 是否需要显式开启扩展语法；
4. 文件是否会传给第三方或跨语言工具链；
5. 是否需要在构建阶段转换为严格 JSON。

常见报错与恢复方法

Unexpected token / 或 Invalid character '/'

通常表示严格解析器遇到了注释。删除注释、改用支持 JSONC/JSON5 的解析器，或在发布前转换为严格 JSON。

VS Code 没有错误，但运行程序失败

这通常是 VS Code 使用了 JSONC 模式，而运行程序使用了标准 JSON 解析器。检查运行程序的配置文档，用同一个解析器进行本地预检，并在 CI 中校验最终产物。

把 # 当成注释

# 不是 JSONC 注释：

{
  # 这不是 JSONC 注释
  "name": "Alice"
}

JSONC 使用的是 // 或 /* ... */。如果你需要 # 注释，应选择支持它的其他配置格式，而不是把文件称为 JSONC。

块注释没有闭合或发生嵌套

检查每个 /* 是否有对应的 */，并移除嵌套块注释。JSONC 和 JSON5 都不支持块注释嵌套。

URL 中的双斜杠被误删

不要使用粗暴的文本替换或正则清理。URL、正则表达式以及字符串中的转义字符都需要由解析器正确识别。

Quick Recap

Bestseller No. 1

Dear Editor

$13.99

如何选择格式

发布前检查清单

• 文件是否必须符合标准 JSON？
• 是否包含 //、/* ... */ 或尾随逗号？
• 目标程序是否明确支持 JSONC 或 JSON5？
• 如果媒体类型是 application/json，发布内容是否为严格 JSON？
• 是否使用实际生产解析器测试过？
• 是否在 CI 中校验最终产物，而不只是编辑器源文件？
• 注释或外部文档中是否泄露密码、令牌或内部信息？

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.