受这条线索的启发，下面是我们正在使用的:

{
  "//dependencies": {
    "crypto-exchange": "Unified exchange API"
  },
  "dependencies": {
    "crypto-exchange": "^2.3.3"
  },
  "//devDependencies": {
    "chai": "Assertions",
    "mocha": "Unit testing framwork",
    "sinon": "Spies, Stubs, Mocks",
    "supertest": "Test requests"
  },
  "devDependencies": {
    "chai": "^4.1.2",
    "mocha": "^4.0.1",
    "sinon": "^4.1.3",
    "supertest": "^3.0.0"
  }
}

正如这个答案所解释的，//键是保留的，所以它可以常规地用于注释。//注释的问题是它不实用，因为它不能被多次使用。在包上删除重复的密钥。Json自动更新:

"//": "this comment about dependencies stays",
"dependencies": {}
"//": "this comment disappears",
"devDependencies": {}

另一个问题是// comment不能在依赖项和devDependencies中使用，因为它被视为常规依赖项:

"dependencies": {
  "//": "comment"
}

npm犯错!代码EINVALIDPACKAGENAME npm犯错!无效的包名“//”:名称只能包含url友好 字符

在NPM中工作的一个变通方法，而不是Yarn，是使用一个非字符串值:

"dependencies": {
  "foo": ["unused package"],
}

一个在NPM和Yarn中工作的变通方法是添加一个注释作为语义版本控制的一部分:

"dependencies": {
  "bar": "^2",
  "foo": "^2 || should be removed in 1.x release"
}

注意，如果OR之前的第一部分不匹配，则可以解析来自注释的版本，例如1.x。

需要注释但没有安装的包应该移动到另一个键，例如dependencies //:

"dependencies //": {
  "baz": "unused package",
}

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

"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删除。

我有一个有趣的黑客想法。

创建一个适当的npm包名，作为文件包中的依赖项和devDependencies块的注释分隔符。Json，例如x----x----x

{
    "name": "app-name",
    "dependencies": {
        "x----x----x": "this is the first line of a comment",
        "babel-cli": "6.x.x",
        "babel-core": "6.x.x",
        "x----x----x": "this is the second line of a comment",
        "knex": "^0.11.1",
        "mocha": "1.20.1",
        "x----x----x": "*"
    }
}

注意:您必须在最后一个注释分隔行中添加一个有效的版本，如块中的*。

As of pnpm 7.17.1, which was just released, you can switch to pnpm for package management, move your package.json to package.json5, and comments in package.json5 are allowed and will be preserved by pnpm. Note however that for publishing as a package to use on the npm registry (for example), a package.json5 will not be recognized by other package managers and I doubt by all of the registry's processing. So you would have to convert the package.json5 to a package.json before publishing. On the other hand, for "top-level applications" that are unlikely to be included as packages in other projects, a package.json5 seems to work just fine, as long as you then stick with pnpm as your package manager.

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

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

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