您总是可以滥用重复的键会被覆盖的事实。这就是我刚才写的:

"dependencies": {
  "grunt": "...",
  "grunt-cli": "...",

  "api-easy": "# Here is the pull request: https://github.com/...",
  "api-easy": "git://..."

  "grunt-vows": "...",
  "vows": "..."
}

然而，不清楚JSON是否允许复制键(参见 JSON语法是否允许在一个对象中重复键?它似乎与npm一起工作，所以我冒这个险。

推荐的破解方法是使用“//”键(来自nodejs邮件列表)。当我测试它时，它不能处理“依赖”部分。另外，文章中的例子使用了多个“//”键，这意味着npm不会拒绝具有重复键的JSON文件。换句话说，上面的hack应该总是好的。

更新:重复密钥的一个恼人的缺点是npm install——save无声地消除了所有重复密钥。不幸的是，它很容易被忽视，你善意的评论也消失了。

“//”攻击看起来仍然是最安全的。但是，多行注释也会被npm install -save删除。

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

{
  "@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期望值为字符串——而不是数组。

在浪费了一个小时的复杂和俗套的解决方案后，我找到了注释package.json中庞大的依赖项部分的简单而有效的解决方案。就像这样:

{
  "name": "package name",
  "version": "1.0",
  "description": "package description",
  "scripts": {
    "start": "npm install && node server.js"
  },
  "scriptsComments": {
    "start": "Runs development build on a local server configured by server.js"
  },
  "dependencies": {
    "ajv": "^5.2.2"
  },
  "dependenciesComments": {
    "ajv": "JSON-Schema Validator for validation of API data"
  }
}

当以同样的方式排序时，现在我很容易在Git提交差异中或在编辑器中跟踪这些依赖/注释对，同时使用package.json文件。

不需要使用额外的工具，只需要简单有效的JSON。

我对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作为句柄模板的上下文。

代码如下，以防有人发现这种方法有用:

const templateData = require('../package.json');
const Handlebars = require('handlebars');
const fs = require('fs-extra');
const outputPath = __dirname + '/../package-json-comments.md';
const srcTemplatePath = __dirname + '/package-json-comments/package-json-comments.hbs';

Handlebars.registerHelper('objlist', function() {
  // The first argument is an object, and the list is a set of keys for that obj
  const obj = arguments[0];
  const list = Array.prototype.slice.call(arguments, 1).slice(0,-1);

  const mdList = list.map(function(k) {
    return '* ' + k + ': ' + obj[k];
  });

  return new Handlebars.SafeString(mdList.join("\n"));
});

fs.readFile(srcTemplatePath, 'utf8', function(err, srcTemplate){
  if (err) throw err;
  const template = Handlebars.compile(srcTemplate);
  const content = template(templateData);

  fs.writeFile(outputPath, content, function(err) {
    if (err) throw err;
  });
});

句柄模板文件package-json-comments.hbs

### Dependency Comments
For package: {{ name }}: {{version}}

#### Current Core Packages
should be safe to update
{{{objlist dependencies
           "@material-ui/core"
           "@material-ui/icons"
           "@material-ui/styles"
}}}

#### Lagging Core Packages
breaks current code if updated
{{{objlist dependencies
           "amazon-cognito-identity-js"
}}}

#### Major version change
Not tested yet
{{{objlist dependencies
           "react-dev-utils"
           "react-redux"
           "react-router"
           "redux-localstorage-simple"

}}}

最近在Node.js邮件列表中讨论了这个问题。

根据创建npm的Isaac Schlueter的说法:

．.． "//"键永远不会被NPM用于任何目的，它是为注释保留的…如果想使用多行注释，可以使用数组或多个“//”键。

当使用你常用的工具(npm, yarn等)时，多个“//”键将被移除。这生存:

{ "//": [
  "first line",
  "second line" ] }

这将不复存在:

{ "//": "this is the first line of a comment",
  "//": "this is the second line of the comment" }

必须注意，"//"只能在包的根目录下使用。json对象。例如 ｛ “/ /”:“评论!” “依赖”:{…} ｝ 是有效的但是 ｛ “依赖”:{ “/ /”:“评论?” ｝ ｝ 是无效的。 ——@david_p评论