总结一下这些答案:

添加一个名为//的顶级字段，其中包含一个注释字符串。这是可行的，但它很糟糕，因为你不能把评论放在他们正在评论的东西附近。 添加多个以//开头的顶级字段，例如包含注释字符串的//dependencies。这样更好，但仍然只允许您做顶级注释。不能注释单个依赖项。 在脚本中添加echo命令。这是可行的，但它很糟糕，因为您只能在脚本中使用它。

这些解决方案的可读性也都不是很好。它们增加了大量的视觉干扰，ide不会用语法将它们作为注释突出显示。

我认为唯一合理的解决方案是生成包。Json从另一个文件。最简单的方法是将JSON写成JavaScript，然后使用Node.js将其写入package.json。将该文件保存为package.json。chmod +x它，然后你可以运行它来生成你的package。json。

#!/usr/bin/env node

import { writeFileSync } from "fs";

const config = {
  // TODO: Think of better name.
  name: "foo",
  dependencies: {
    // Bar 2.0 does not work due to bug 12345.
    bar: "^1.2.0",
  },
  // Look at these beautify comments. Perfectly syntax highlighted, you
  // can put them anywhere and there no risk of some tool removing them.
};

writeFileSync("package.json", JSON.stringify({
    "//": "This file is \x40generated from package.json.mjs; do not edit.",
    ...config
  }, null, 2));

它使用//键来警告人们不要编辑它。\x40生成是故意的。它变成了@generated in package。Json，这意味着一些代码审查系统将在默认情况下崩溃该文件。

这是构建系统中的一个额外步骤，但它胜过这里的所有其他hack。

因为大多数开发人员都熟悉基于标记/注释的文档，所以我开始使用的约定是类似的。来尝尝:

{
  "@comment dependencies": [
    "These are the comments for the `dependencies` section.",
    "The name of the section being commented is included in the key after the `@comment` 'annotation'/'tag' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient to keep keys unique if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multi-line string or understand a line continuation operator/character, just use an array for each line of the comment.",
    "Since this is embedded in JSON, the keys should be unique.",
    "Otherwise JSON validators, such as ones built into IDEs, will complain.",
    "Or some tools, such as running `npm install something --save`, will rewrite the `package.json` file but with duplicate keys removed.",
    "",
    "@package react - Using an `@package` 'annotation` could be how you add comments specific to particular packages."
  ],
  "dependencies": {
    ...
  },
  "@comment scripts": {
    "build": "This comment is about the build script.",
    "start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "test": "This comment is about the test script.",
  },
  "scripts": {
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

注意:对于dependencies、devDependencies等部分，注释注释不能直接添加到配置对象中各个包依赖项的上面，因为npm期望键是npm包的名称。这就是@comment依赖的原因。

我喜欢在JSON中添加注释的注释/标记样式，因为@符号与普通声明不同。

年长的建议

以下是我之前的建议。它内联注释的脚本，但我已经意识到，这些注释显示为“命令”在一些工具(在VS Code > Explorer > NPM脚本部分)。最新的建议没有受到这个问题的影响，但是脚本注释不再位于同一位置。

{
  "@comment dependencies": [
    ...
  ],
  "dependencies": {
    ...
  },
  "scripts": {
    "@comment build": "This comment is about the build script.",
    "build": "...",

    "@comment start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "start": "...",

    "@comment test": "This comment is about the test script.",
    "test": "..."
  }
}

注意:在某些情况下，例如在“scripts”对象中，一些编辑器/ ide可能会抱怨数组。在脚本上下文中，VS Code期望值为字符串——而不是数组。

总结一下这些答案:

添加一个名为//的顶级字段，其中包含一个注释字符串。这是可行的，但它很糟糕，因为你不能把评论放在他们正在评论的东西附近。 添加多个以//开头的顶级字段，例如包含注释字符串的//dependencies。这样更好，但仍然只允许您做顶级注释。不能注释单个依赖项。 在脚本中添加echo命令。这是可行的，但它很糟糕，因为您只能在脚本中使用它。

这些解决方案的可读性也都不是很好。它们增加了大量的视觉干扰，ide不会用语法将它们作为注释突出显示。

我认为唯一合理的解决方案是生成包。Json从另一个文件。最简单的方法是将JSON写成JavaScript，然后使用Node.js将其写入package.json。将该文件保存为package.json。chmod +x它，然后你可以运行它来生成你的package。json。

#!/usr/bin/env node

import { writeFileSync } from "fs";

const config = {
  // TODO: Think of better name.
  name: "foo",
  dependencies: {
    // Bar 2.0 does not work due to bug 12345.
    bar: "^1.2.0",
  },
  // Look at these beautify comments. Perfectly syntax highlighted, you
  // can put them anywhere and there no risk of some tool removing them.
};

writeFileSync("package.json", JSON.stringify({
    "//": "This file is \x40generated from package.json.mjs; do not edit.",
    ...config
  }, null, 2));

它使用//键来警告人们不要编辑它。\x40生成是故意的。它变成了@generated in package。Json，这意味着一些代码审查系统将在默认情况下崩溃该文件。

这是构建系统中的一个额外步骤，但它胜过这里的所有其他hack。

我对JSON中没有注释的沮丧之处的看法。我创建了新节点，以它们所引用的节点命名，但以下划线作为前缀。这是不完美的，但功能。

{
  "name": "myapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "react": "^16.3.2",
    "react-dom": "^16.3.2",
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "__start": [
        "a note about how the start script works"
    ],
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject"
  },
  "__proxy": [
    "A note about how proxy works",
    "multilines are easy enough to add"
  ],
  "proxy": "http://server.whatever.com:8000"
}

由于重复的注释键被删除运行包。json工具(npm, yarn等)，我开始使用散列版本，允许更好地阅读多行和键，如:

"//": {
  "alpaca": "we use the bootstrap version",
  "eonasdan-bootstrap-datetimepicker": "instead of bootstrap-datetimepicker",
  "moment-with-locales": "is part of moment"
},

根据我的IDE作为根键，这是“有效的”，但在依赖关系中，它抱怨期望字符串值。

以下是我对包内评论的看法。Json / bower.json:

我有文件package.json.js，其中包含一个脚本，导出实际的package.json。运行脚本将覆盖旧包。Json并告诉我它所做的更改，完美地帮助你跟踪NPM所做的自动更改。这样，我甚至可以通过编程方式定义我想要使用的包。

最新的Grunt任务如下: https://gist.github.com/MarZab/72fa6b85bc9e71de5991