传递参数和添加注释

本章将介绍三个提升 npm script 可用性和可维护性的技巧：如何向脚本传递参数以增强复用性，如何为脚本添加注释以提高可读性，以及如何控制日志输出级别以辅助调试。

向 npm script 传递参数

许多命令行工具通过参数来启用特定功能。例如，ESLint 的 --fix 参数可以自动修复代码风格问题。一种常见的做法是为同一任务创建两个脚本，一个用于检查，一个用于修复：

json

"scripts": {
  "lint:js": "eslint *.js",
  "lint:js:fix": "eslint *.js --fix"
}

这种方式虽然简单，但存在维护性问题：如果 lint:js 的命令发生变化，我们很可能会忘记同步更新 lint:js:fix。

更健壮的做法是利用 npm 的参数透传机制。我们可以在执行 npm run 命令时，通过在末尾添加 -- 分隔符，将额外的参数传递给脚本实际调用的命令。

json

"scripts": {
  "lint:js": "eslint *.js",
  "lint:js:fix": "npm run lint:js -- --fix"
}

现在，执行 npm run lint:js:fix 时，npm 会将 --fix 参数正确地传递给 eslint 命令。这样，lint:js:fix 始终与 lint:js 保持同步。

提示：你也可以不创建新脚本，直接在运行时传递参数，例如：npm run lint:js -- --fix。这个技巧同样适用于其他命令，比如为 mocha 添加 --watch 模式：npm test -- --watch。

随着 scripts 增多，为复杂的命令添加注释变得至关重要。然而，JSON 格式本身不支持注释。社区探索出了一些变通方法，但它们各有优劣。

方法一：利用 // 键

package.json 中可以添加一个以 // 为键的字段，npm 会忽略它。你可以将注释写在这个字段的值里。

json

"scripts": {
  "//": "运行所有代码检查和单元测试",
  "test": "npm-run-all --parallel lint:* mocha"
}

这种方法的缺点是，当执行 npm run 查看所有脚本时，注释与命令无法一一对应。

方法二：利用 shell 注释

由于 npm script 本质上是 shell 命令，我们可以利用 shell 的 # 注释符。通过换行符 \n，可以将注释和命令分隔开。

json

"scripts": {
  "test": "# 运行所有代码检查和单元测试 \n npm-run-all --parallel lint:* mocha"
}

这种方式虽然能在 npm run 的输出中显示注释，但 package.json 文件本身会显得杂乱，可读性不佳。

最佳实践：以上两种方法都有明显缺陷。更推荐的做法是将复杂的脚本逻辑拆分到单独的 shell 或 Node.js 文件中。在这些文件中，你可以自由地添加注释，从而保持 package.json 的整洁与可读性。我们将在后续章节详细探讨这一模式。

调整 npm script 的日志输出级别，可以帮助我们专注于关键信息或获取详细的调试线索。

默认级别：不加任何参数时，npm 会显示执行的命令、命令的输出以及最终结果。这是最常用的级别。
静默模式 (--silent 或 -s)：此模式下，npm 不会输出自身执行信息，只显示脚本本身的输出。这在与其他工具集成或希望保持终端清爽时非常有用。如果一个 lint 脚本在静默模式下没有任何输出，通常意味着“没有消息就是最好的消息”。
bash
```
npm run lint:js --silent
```
详细模式 (--verbose 或 -d)：此模式用于问题排查，npm 会打印出每个执行步骤的详细信息，包括参数、环境变量和返回值。
bash
```
npm run test --verbose
```

本节的示例代码已上传至 GitHub。你可以克隆该仓库并切换到 03-arguments-comments-logs 分支进行练习。