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

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

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

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"
}

到目前为止，这里的大多数“黑客”都建议滥用JSON。但是，为什么不滥用底层脚本语言呢?

最初的反应是把描述放在右边，使用# add comments here来包装它;然而，这在Windows上不起作用，因为标志(例如，npm run myframework -- --myframework-flags)将被忽略。我改变了我的响应，使其适用于所有平台，并增加了一些缩进的可读性。

{
 "scripts": {
    "help": "       echo 'Display help information (this screen)';          npm run",
    "myframework": "echo 'Run myframework binary';                          myframework",
    "develop": "    echo 'Run in development mode (with terminal output)';  npm run myframework"
    "start": "      echo 'Start myFramework as a daemon';                   myframework start",
    "stop":  "      echo 'Stop the myFramework daemon';                     myframework stop"
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

这将:

Not break JSON compliance (or at least it's not a hack, and your IDE will not give you warnings for doing strange, dangerous stuff) Works cross platform (tested on macOS and Windows, assuming it would work just fine on Linux) Does not get in the way of running npm run myframework -- --help Will output meaningful info when running npm run (which is the actual command to run to get information about available scripts) Presents a more explicit help command (in case some developers are not aware that npm run presents such output) Will show both the commands and its description when running the command itself Is somewhat readable when just opening package.json (using less or your favorite IDE)

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

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

我做了一些你们可能会喜欢的事情:

这个//在名字里面意味着它是我的注释:

  "//":"Main and typings are used till ES5",
  "//main": "build/index",
  "//typings": "build/index",

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

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