如何为 npm 脚本提供使用信息

Question

有没有一种简单的方法可以提供 npm 脚本的使用信息？

理想情况下，当我运行 npm run 时，我会得到这样的输出（注意每个任务底部的描述）：

Lifecycle scripts included in product-discovery-service:
  start
    node server.js

available via `npm run-script`:
  watch
    run-p watch:build watch:run
    Run in development mode and rebuild/restart when changes are made
  watch:build
    npm run build:dev -- --watch
    Probably don't need this (would be nice to be able to omit tasks like this)
  watch:run
    nodemon --watch build/ --inspect
    Probably don't need this (would be nice to be able to omit tasks like this)
  prewatch:run
    wait-on --log build/server.js
    Probably don't need this (would be nice to be able to omit tasks like this)
  build
    babel server.js --out-dir build/
    Build the project
  prebuild
    rimraf build/
    Probably don't need this (would be nice to be able to omit tasks like this)
  build:dev
    npm run build -- --source-maps
    Probably don't need this (would be nice to be able to omit tasks like this)

貌似npm不支持这个，但也许有第三方有解决方案？我找到了 npm-scripts-help，但感觉很笨拙。

Answer 1

简答：

是的，你是对的，当运行 npm run 时，npm 不提供包含描述的内置功能。因此，您选择的任何解决方案都会有一定程度的 "feels clunky" 与之关联。

正如你所提到的 npm-scripts-help 是一个可以实现这一点的包。我不知道其他类似的第三方解决方案。

替代自定义解决方案：

以下步骤描述了如何编写一个简单的自定义 Nodejs 实用程序脚本（不使用其他第三方包依赖项）。然后可以通过 npm-scripts 调用此脚本。

创建一个简单的 Nodejs 实用脚本如下。让我们将文件命名为 usage.js.

usage.js

const usage = `
  Lifecycle scripts included in ${process.env.npm_package_name}:
  start
    node server.js

available via \`npm run-script\`:
  watch
    run-p watch:build watch:run
    Run in development mode and rebuild/restart when changes are made
  watch:build
    npm run build:dev -- --watch
    Probably don't need this (would be nice to be able to omit tasks like this)
  watch:run
    nodemon --watch build/ --inspect
    ...`

console.log('%s', usage);

将 usage.js 保存在与 package.json 相同级别的项目根目录中。
将以下 usage 脚本添加到 package.json 的 scripts 部分：
```
...
"scripts": {
  "usage": "node usage",
  ...
},
...
```
运行 npm run usage 将使用信息打印到控制台。 npm run 必须提供脚本名称（即 usage）。不幸的是，你的理想运行 npm run 只会记录 npm 的简单日志 - 不包括描述。

备注：

在 usage.js 的第二行，我们通过以下部分引用包名称变量：${process.env.npm_package_name}
如果您更改项目目录中 usage.json 的存储位置，您将需要根据需要在 npm 脚本中重新定义它的路径。例如，如果您选择将它存储在名为 scripts 的文件夹中，该文件夹位于您的项目根目录中，那么您的 usage 脚本应定义如下：
```
...
"scripts": {
  "usage": "node scripts/usage",
  ...
},
...
```

添加ANSI/VT100控制序列

您可以利用 usage.js 中的 ANSI/VT100 Control sequences 为使用日志添加颜色和格式。

例如，在下面的usage.js中，代码：

\x1b[1m
\x1b[0m

...分别用于增强代码片段和将格式重置为默认值。

提示：如果需要跨平台，我建议仅使用 ANSI 8/16 颜色（在前面的 link 中列出）。粗体 (\x1b[1m) 的格式代码在 Windows cmd.exe 中无法使用 Windows 等终端命令提示符 或 PowerShell.

usage.js（带格式）

const BOLD = '\x1b[1m';
const NORM = '\x1b[0m';

const formattedUsage = `
Lifecycle scripts included in ${BOLD}${process.env.npm_package_name}:${NORM}
  ${BOLD}start
    node server.js${NORM}

available via ${BOLD}npm run-script${NORM}
  ${BOLD}watch
    run-p watch:build watch:run${NORM}
    Run in development mode and rebuild/restart when changes are made
  ${BOLD}watch:build
    npm run build:dev -- --watch${NORM}
    ...`

console.log('%s', formattedUsage);

您还可以考虑结合使用 ES6 Template Literals with process.env and package.json vars 来引用每个 npm 脚本的值。例如：

`${BOLD}${process.env.npm_package_scripts_watch}:${NORM}`

如何为 npm 脚本提供使用信息

How to provide usage information for npm scripts

command-line-interface

npm

npm-scripts

简答：

替代自定义解决方案：