如何提供 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 不提供在运行npm run 时包含描述的内置功能。因此，您选择的任何解决方案都会有某种程度的“感觉很笨重”。

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

---

替代自定义解决方案：

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

1. 如下创建一个简单的 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);
   

2. 将usage.js保存在您的项目根目录中，与存储package.json的级别相同。

3. 将以下usage 脚本添加到package.json 的scripts 部分：

   ...
   "scripts": {
     "usage": "node usage",
     ...
   },
   ...
   

4. 运行npm run usage 将使用信息打印到控制台。脚本名称（即usage）必须与npm run 一起提供。不幸的是，您只运行 npm run 的理想只会记录 npm 的简单日志 - 不包括描述。

注意事项：

• 在usage.js 的第二行，我们通过以下部分引用包名变量：${process.env.npm_package_name}

• 如果您更改 usage.json 在项目目录中的存储位置，则需要根据需要在 npm-script 中重新定义它的路径。例如，如果您选择将其存储在一个名为 scripts 的文件夹中，该文件夹位于您的项目根目录中，那么您的 usage 脚本应定义如下：

  ...
  "scripts": {
    "usage": "node scripts/usage",
    ...
  },
  ...
  

---

添加 ANSI/VT100 控制序列

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

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

• \x1b[1m
• \x1b[0m

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

提示：如果需要跨平台，我建议仅使用 ANSI 8/16 颜色（在上一个链接中列出）。 bold (\x1b[1m) 的格式代码在使用 Windows 命令提示符 或 PowerShell 等终端的 Windows cmd.exe 中不起作用。

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 与process.env 和package.json vars 结合起来引用每个npm-script 的值。例如：

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