小程序中json中怎么注释

小程序中JSON文件如何添加注释？实用技巧与注意事项

在微信、支付宝等小程序开发中，json文件扮演着至关重要的角色——它用于配置页面路径、窗口样式、tab栏、组件引用等全局或局部设置，与支持或注释的js、css文件不同，JSON本身是无注释格式的规范，直接在JSON文件中添加注释会导致解析失败，引发配置错误，开发者如何在保持JSON格式有效性的的同时，为配置添加说明性内容呢？本文将结合实际场景，介绍小程序JSON文件的“注释”实现方案。

为什么JSON文件不能直接加注释？

首先需要明确：JSON（JavaScript Object Notation）的设计初衷是轻量级数据交换格式，其核心要求是“简洁”和“无歧义”，根据JSON规范（RFC 8259），标准JSON文本中不允许出现注释、尾随逗号、未加引号的键名等语法，否则会被解析器视为无效格式。

在小程序开发中，框架会读取并解析app.json、page.json等配置文件，若文件中包含注释（如"navigationBarTitleText": "首页" // 页面标题），小程序引擎将无法正确解析配置，可能导致页面无法加载、样式失效等问题，直接在JSON中写注释是“行不通”的”。

实用替代方案：如何实现“注释”效果？

虽然JSON本身不支持注释，但开发者可以通过以下几种方法，在保证格式有效性的前提下,实现配置说明的功能：

通过“键值对”模拟注释（推荐）

最直接的方法是使用“无实际意义”的键值对来存储说明信息，通常以_或__开头，避免与实际配置冲突，在app.json中添加页面说明：

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ],
  "_pageNote": "首页和日志页的配置，请勿随意修改页面路径",
  "window": {
    "navigationBarTitleText": "小程序示例"
  }
}

优点：

完全符合JSON规范，不影响小程序解析；
直观易懂，通过键名即可区分说明内容和实际配置。

适用场景：

全局配置文件（如app.json）中添加整体说明；
页面配置文件（如page.json）中标注特定字段的用途。

使用“描述性字段”替代注释

对于复杂配置（如tabBar、usingComponents），可以通过添加专门的“描述字段”来解释配置逻辑。

{
  "tabBar": {
    "color": "#999999",
    "selectedColor": "#1AAD19",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png",
        "_desc": "首页配置，包含图标和选中状态"
      },
      {
        "pagePath": "pages/user/index",
        "text": "我的",
        "iconPath": "images/user.png",
        "selectedIconPath": "images/user-active.png",
        "_desc": "用户中心配置，需关联用户登录状态"
      }
    ],
    "_note": "tabBar栏配置，最多5个标签，图标尺寸建议81px"
  }
}

优点：

将注释与配置绑定，避免说明与实际配置分离；
适合团队协作，通过字段名明确“这是说明内容”。

注意事项：

描述字段需以特殊符号（如_、）开头，避免与小程序保留字段冲突；
不要在描述字段中存储核心配置，仅用于说明。

通过外部文档+代码注释（团队协作首选）

对于大型项目或复杂配置，单纯依赖JSON内“模拟注释”可能不够清晰，此时可结合外部文档和代码注释：

JSON文件：保持无注释，仅写核心配置；
外部文档：在项目README、Wiki或Confluence中记录JSON配置的说明、字段含义、修改注意事项；
代码注释：在引用JSON文件的js/ts代码中添加注释，

// app.json - 全局配置文件
// 包含页面路由、窗口样式、tab栏等核心设置
// 最后更新：2023-10-01，更新人：张三
const appConfig = require('./app.json')
Page({
  onLoad() {
    console.log('当前页面标题：', appConfig.window.navigationBarTitleText)
  }
})

优点：

文档和代码分离，注释更系统化，适合多人协作；
可通过文档工具（如Markdown）实现富文本说明（表格、截图等），更易理解。

适用场景：

企业级项目、团队开发中需要长期维护的配置；
配置逻辑复杂，需详细说明字段关联关系的情况。

使用“JSON5”或“JSON with Comments”扩展格式（需构建工具支持）

如果项目允许使用构建工具（如Webpack、Vite），可通过插件支持“带注释的JSON”扩展格式（如JSON5、JSONC），在微信小程序中使用miniprogram-ci构建时，可配置JSON5解析：

安装JSON5解析器：npm install json5
在构建脚本中引入JSON5解析配置文件：

// app.json5（支持注释）
{
  "pages": ["pages/index/index"],
  // 全局窗口配置
  "window": {
    "navigationBarTitleText": "示例小程序" // 标题文本
  }
}

构建时通过工具将.json5文件转换为标准.json文件（移除注释）。

优点：

开发时可写注释，提升可读性；
构建后自动生成标准JSON，不影响小程序运行。

缺点：

需额外配置构建工具，增加项目复杂度；
不适合纯原生开发（未使用构建工具的项目）。

注意事项：这些“坑”要避开

避免“假注释”干扰解析
即使使用“模拟注释”，也要确保JSON格式正确，例如键值对必须加双引号、不能有尾随逗号：

// 错误示例：尾随逗号
{
  "pages": ["pages/index/index"],
  "_note": "页面配置", // 逗号会导致解析失败
}
// 正确示例
{
  "pages": ["pages/index/index"],
  "_note": "页面配置"
}

描述字段命名规范
统一使用_或__作为描述字段前缀，避免与小程序官方字段冲突（如window、tabBar等），可通过团队文档明确命名规则,防止误用。
复杂配置优先文档说明
对于多层嵌套配置（如usingComponents组件引用、permission权限配置），单纯依赖JSON内“模拟注释”可能不够清晰,建议结合外部文档或代码注释补充说明。