正如这个答案所解释的，//键是保留的，所以它可以常规地用于注释。//注释的问题是它不实用，因为它不能被多次使用。在包上删除重复的密钥。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",
}

NPS(节点包脚本)为我解决了这个问题。它允许你把NPM脚本放到一个单独的JavaScript文件中，在那里你可以添加大量的注释和任何其他你需要的JavaScript逻辑。 https://www.npmjs.com/package/nps

来自我的一个项目的package-scripts.js示例

module.exports = {
  scripts: {
    // makes sure e2e webdrivers are up to date
    postinstall: 'nps webdriver-update',

    // run the webpack dev server and open it in browser on port 7000
    server: 'webpack-dev-server --inline --progress --port 7000 --open',

    // start webpack dev server with full reload on each change
    default: 'nps server',

    // start webpack dev server with hot module replacement
    hmr: 'nps server -- --hot',

    // generates icon font via a gulp task
    iconFont: 'gulp default --gulpfile src/deps/build-scripts/gulp-icon-font.js',

    // No longer used
    // copyFonts: 'copyfiles -f src/app/glb/font/webfonts/**/* dist/1-0-0/font'
  }
}

我只是做了一个本地安装npm安装nps -save-dev，并把它放在我的包。json脚本。

"scripts": {
    "start": "nps",
    "test": "nps test"
}

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

创建一个适当的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": "*"
    }
}

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

我最终得到了这样一个脚本:

  "scripts": {
    "//-1a": "---------------------------------------------------------------",
    "//-1b": "---------------------- from node_modules ----------------------",
    "//-1c": "---------------------------------------------------------------",
    "ng": "ng",
    "prettier": "prettier",
    "tslint": "tslint",
    "//-2a": "---------------------------------------------------------------",
    "//-2b": "--------------------------- backend ---------------------------",
    "//-2c": "---------------------------------------------------------------",
    "back:start": "node backend/index.js",
    "back:start:watch": "nodemon",
    "back:build:prod": "tsc -p backend/tsconfig.json",
    "back:serve:prod": "NODE_ENV=production node backend/dist/main.js",
    "back:lint:check": "tslint -c ./backend/tslint.json './backend/src/**/*.ts'",
    "back:lint:fix": "yarn run back:lint:check --fix",
    "back:check": "yarn run back:lint:check && yarn run back:prettier:check",
    "back:check:fix": "yarn run back:lint:fix; yarn run back:prettier:fix",
    "back:prettier:base-files": "yarn run prettier './backend/**/*.ts'",
    "back:prettier:fix": "yarn run back:prettier:base-files --write",
    "back:prettier:check": "yarn run back:prettier:base-files -l",
    "back:test": "ts-node --project backend/tsconfig.json node_modules/jasmine/bin/jasmine ./backend/**/*spec.ts",
    "back:test:watch": "watch 'yarn run back:test' backend",
    "back:test:coverage": "echo TODO",
    "//-3a": "---------------------------------------------------------------",
    "//-3b": "-------------------------- frontend ---------------------------",
    "//-3c": "---------------------------------------------------------------",
    "front:start": "yarn run ng serve",
    "front:test": "yarn run ng test",
    "front:test:ci": "yarn run front:test --single-run --progress=false",
    "front:e2e": "yarn run ng e2e",
    "front:e2e:ci": "yarn run ng e2e --prod --progress=false",
    "front:build:prod": "yarn run ng build --prod --e=prod --no-sourcemap --build-optimizer",
    "front:lint:check": "yarn run ng lint --type-check",
    "front:lint:fix": "yarn run front:lint:check --fix",
    "front:check": "yarn run front:lint:check && yarn run front:prettier:check",
    "front:check:fix": "yarn run front:lint:fix; yarn run front:prettier:fix",
    "front:prettier:base-files": "yarn run prettier \"./frontend/{e2e,src}/**/*.{scss,ts}\"",
    "front:prettier:fix": "yarn run front:prettier:base-files --write",
    "front:prettier:check": "yarn run front:prettier:base-files -l",
    "front:postbuild": "gulp compress",
    "//-4a": "---------------------------------------------------------------",
    "//-4b": "--------------------------- cypress ---------------------------",
    "//-4c": "---------------------------------------------------------------",
    "cy:open": "cypress open",
    "cy:headless": "cypress run",
    "cy:prettier:base-files": "yarn run prettier \"./cypress/**/*.{js,ts}\"",
    "cy:prettier:fix": "yarn run front:prettier:base-files --write",
    "cy:prettier:check": "yarn run front:prettier:base-files -l",
    "//-5a": "---------------------------------------------------------------",
    "//-5b": "--------------------------- common ----------------------------",
    "//-5c": "---------------------------------------------------------------",
    "all:check": "yarn run back:check && yarn run front:check && yarn run cy:prettier:check",
    "all:check:fix": "yarn run back:check:fix && yarn run front:check:fix && yarn run cy:prettier:fix",
    "//-6a": "---------------------------------------------------------------",
    "//-6b": "--------------------------- hooks -----------------------------",
    "//-6c": "---------------------------------------------------------------",
    "precommit": "lint-staged",
    "prepush": "yarn run back:lint:check && yarn run front:lint:check"
  },

我在这里的目的不是澄清一行，只是在后台、前端、所有等脚本之间使用某种分隔符。

我不太喜欢1a、1b、1c、2a……但钥匙是不同的，我没有任何问题，像这样。

总结一下这些答案:

添加一个名为//的顶级字段，其中包含一个注释字符串。这是可行的，但它很糟糕，因为你不能把评论放在他们正在评论的东西附近。 添加多个以//开头的顶级字段，例如包含注释字符串的//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期望值为字符串——而不是数组。