最大的Node.js CLI应用程序最佳实践列表 ✨

关于如何构建成功的、有共鸣的和用户友好的Node.js命令行界面（CLI）应用程序的最佳实践的汇编。

为什么是这个指南？

一个糟糕的CLI很容易使用户不愿意与它互动。构建成功的CLI需要关注细节和对用户的同情，以便创造良好的用户体验。这是很容易出错的。

在本指南中，我汇编了一份重点领域的最佳实践清单，旨在优化与CLI应用程序交互时的理想用户体验。

特点。

• 构建成功的Node.js CLI应用程序的21个最佳实践
• ✅用不同的语言阅读。 ??, ??, 或帮助翻译成其他语言。[ ??, ...]
• ?欢迎投稿

为什么是我？

大家好，我是Liran Tal，我沉迷于构建命令行应用程序。

我最近的一些工作，构建Node.js CLI，包括以下开源项目。

团队✨

感谢这些优秀的人（表情符号键）。

Vanilla
?

特克尔
?

Jason Karns
?

戴夫-萨格
?

José J. Pérez Rivas
?

苏雷什拉吉
?

目录

• 1 命令行经验
  • 1.1尊重POSIX args
  • 1.2构建移情的CLI
  • 1.3有状态的数据
  • 1.4提供丰富多彩的体验
  • 1.5丰富的交互性
  • 1.6无处不在的超链接
  • 1.7零配置
  • 1.8尊重POSIX信号
• 2 分布
  • 2.1 倾向于小的依赖足迹
  • 2.2使用缩略图，卢克
  • 2.3清理配置文件
• 3 互操作性
  • 3.1接受输入为STDIN
  • 3.2启用结构化输出
  • 3.3跨平台的礼节
  • 3.4支持配置优先级
• 4 可访问性
  • 4.1容器化CLI
  • 4.2优雅降级
  • 4.3Node.js版本兼容
  • 4.4Shebang自动检测Node.js的运行时间
• 5 测试
  • 5.1不信任地域性
• 6 错误
  • 6.1可追踪的错误
  • 6.2可操作的错误
  • 6.3提供调试模式
  • 6.4正确使用退出代码
  • 6.5不费吹灰之力的错误报告
• 7 开发
  • 7.1使用bin对象
  • 7.2使用相对路径
  • 7.3使用文件字段

1 命令行体验

本节涉及与创建漂亮和高价值的用户体验Node.js命令行应用程序有关的最佳实践。

在本节中。

• 1.1尊重POSIX args

• 1.2构建移情的CLI

• 1.3有状态的数据

• 1.4提供丰富多彩的体验

• 1.5丰富的互动

• 1.6无处不在的超链接

• 1.7零配置

• 1.8尊重POSIX信号

1.1 尊重POSIX参数

✅ **做：**使用符合POSIX标准的命令行参数语法，这被广泛接受为命令行工具的标准。

**否则：**当CLI的参数、选项或命令参数的语法与他们习惯的事实上的Unix标准相背离时，用户可能会感到沮丧。

ℹ️ 细节

类Unix操作系统普及了命令行和工具的使用，如awk,sed 。这些工具有效地规范了命令行选项（又称标志）、选项-参数和其他操作数的行为。

一些预期行为的例子。

• 选项-参数或选项可以在帮助或例子中用方括号 ([]) 表示它们是可选的，或用角括号 (<>) 表示它们是必须的。
• 允许短形式的单字母参数作为长形式参数的别名（参见GNU编码标准的参考）。
• 使用短形式的单数- 的选项可以包含一个字母数字字符。
• 指定多个无值的选项可以分组，例如myCli -abc 等同于myCli -a -b -c 。

命令行用户会希望你的命令行应用程序与其他Unix应用程序有类似的约定。

? 推荐的软件包

参考开源Node.js包。

• yargs

1.2 构建移情的CLI

✅ **做：**建立工作流程，协助用户与CLI成功互动，否则这种互动会导致错误和挫败感。

**否则：**如果不能提供可操作的帮助来支持用户，将导致用户因缺乏操作CLI的能力而产生挫败感。

ℹ️ 细节

你的程序的命令行界面和网络用户界面没有什么不同，作为程序的作者，你要尽最大努力确保它被成功使用。

通过建立支持用户的共鸣式CLI，来优化成功的交互。作为一个例子，让我们探讨一下curl 程序的情况，该程序期望一个URL作为其主要的数据输入，而用户未能提供它。这样的失败会导致用户阅读（希望是）描述性的错误信息，或者查看curl --help 输出。然而，一个有同理心的CLI会提出一个交互式的提示来捕捉用户的输入，从而导致一个成功的交互。

1.3 有状态的数据

✅ **做：**在你的CLI应用的多次调用之间提供一个有状态的体验，并记住值和数据，以提供无缝交互。

**否则：**要求你的用户在多次调用CLI时重复提供相同的信息会使你的用户感到厌烦。

ℹ️ 细节

你可能会发现自己需要为你的CLI应用提供存储持久性，比如在CLI的多次调用中记住一个用户名、电子邮件、API令牌或其他偏好。使用一个配置助手，使应用程序能够持久化这种用户设置。在读/写文件时一定要遵循XDG基本目录规范（或者选择一个尊重该规范的配置助手）。这些使用户保持对文件写入和管理位置的控制。

参考项目。

• configstore
• conf

1.4 提供多彩的体验

✅ **做到：**在你的CLI应用程序中使用颜色，以突出你的应用程序的输出部分，并提供一个优雅的退化，或颜色检测，以允许自动选择退出，以便输出不会乱码。确保通过CLI选项、环境变量和/或配置文件可以手动选择进入和退出。

**否则：**信息可能很容易在苍白的程序输出中丢失，特别是当输出是大量文字时。

ℹ️ 细节

今天，大多数用于与命令行程序交互的终端都支持彩色文本，如这些由专门制作的ANSI编码字符启用的彩色文本。

在你的命令行应用程序输出中的彩色显示可能会进一步促进更丰富的体验和增加互动。也就是说，不支持的终端可能会出现屏幕上的信息混乱的形式，从而导致输出效果下降。此外，CLI可能被用于持续集成的构建工作中，这可能不支持彩色输出。即使在构建服务器之外，CLI也可能通过IDE的控制台使用，该控制台可能无法处理某些字符。必须提供手动选择退出。

参考项目。

• 白垩
• 颜色
• kleur

? 推荐软件包

参考开源Node.js包。

• 白垩纪
• 颜色
• kleur

1.5 丰富的交互方式

✅ **做：**利用丰富的命令行交互，超越基本的文本输入提示，为CLI用户提供更顺畅的体验。

**否则：**当需要推理的数据是以封闭的选项（即下拉菜单）的形式出现时，作为输入的文本提示可能会给用户带来麻烦。

ℹ️ 细节

丰富的交互性可以以提示输入的形式引入，这比自由文本更复杂，如下拉选择列表、单选按钮切换、评级、自动完成或隐藏密码输入。

另一种丰富的交互性是以动画加载器和进度条的形式出现的，在进行异步工作时为用户提供了更好的体验。

许多CLI提供默认的命令行参数，而不需要任何进一步的交互体验。不要强迫你的用户提供应用可以自己解决的参数。

? 推荐的软件包

参考开源Node.js包。

• enquirer
• ora
• 墨水
• 提示语

1.6 超链接无处不在

✅ **做到：**在文本输出中对URL（如：https://www.github.com ）以及源代码（如：src/Util.js:2:75 ）使用正确格式的超链接--现代终端能够将这两者转化为可点击的链接。

❌ **否则：**避免像git.io/abc 这样需要用户手动复制和粘贴的破碎和非交互式链接。

ℹ️ 细节

如果你分享的是URL的链接，或指向一个文件和文件中的特定行号和列，你可以为这两个例子提供正确格式的链接，一旦点击，就会打开浏览器，或定义位置的IDE。

参考项目。

• 打开

1.7 零配置

✅ **做：**通过自动检测所需的配置和命令行参数值来优化即插即用的体验。

**否则：**如果能以可靠的方式自动检测到命令行参数，并且调用的操作没有明确要求用户交互（如确认删除），则不要强迫用户交互。

ℹ️ 细节

争取在运行CLI应用程序时提供 "开箱即用 "的体验。 例如，POSIX定义了一个用于不同目的的环境变量配置标准，如：TMPDIR,NO_COLOR,DEBUG,HTTP_PROXY 等。自动检测这些，必要时提示确认。

参考那些围绕零配置的项目。

• Jest JavaScript测试框架
• Parcel，一个网络应用程序捆绑器

1.8 尊重POSIX信号

✅ **做：**确保你的程序尊重POSIX信号，以便与用户或其他程序进行适当的互动。

**否则：**你的程序将不能与其他程序很好地互动，并会带来意想不到的行为。

ℹ️ 细节

特别是对于CLI应用程序来说，与用户输入进行交互是很常见的，不适当地管理键盘事件可能会导致你的应用程序无法响应SIGINT中断，用户在点击CTRL+C 键时通常会使用这种中断。

当程序被非人类的互动所协调时，不尊重进程信号的问题就会恶化。例如，一个在docker容器中运行的CLI，但不会对发给它的软件中断信号做出响应。

2 分布

本节涉及有关以最佳方式为消费者分发和打包Node.js命令行应用程序的最佳实践。

在本节中。

• 2.1倾向于选择一个小的依赖足迹
• 2.2使用shrinkwrap, Luke
• 2.3清理配置文件

2.1 倾向于小的依赖性足迹

**做法：**尽量减少对生产依赖的使用，使用更小的替代依赖，并对依赖的足迹进行审查，以确保Node.js CLI的一个小捆。平衡这一点，注意不要通过重新发明轮子来过度优化依赖关系的使用。

**否则：**应用程序中依赖关系的大小和使用将影响你的Node.js CLI的安装时间，可能会提供一个糟糕的用户体验。

ℹ️ 详细信息

用npx 调用的Node.js CLI的快速npm install ，将提供更好的用户体验。当整个依赖关系和跨依赖关系的足迹被保持在一个合理的大小时，这才有可能。

一次性的全局npm 安装一个安装缓慢的npm 包将提供一次性的糟糕体验，但用户使用npx 来调用可执行包将使性能下降，由于npx 总是从注册表中获取和安装包，这一点更加显著和明显。

参考项目。

• Bundlephobia是一个帮助你找到npm包的成本的工具。

2.2 使用shrinkwrap，Luke

✅ **做：**使用npm的npm-shrinkwrap.json 作为锁定文件，以确保钉子式的依赖版本（直接和横向）在你的终端用户安装你的npm包时传播给他们。

❌ **否则：**不固定你的应用程序的依赖版本将意味着软件包管理器（例如npm ）将在安装过程中解决这些问题，通过版本范围安装的横向依赖可能会引入你无法控制的破坏性变化，这可能导致你的Node.js CLI应用程序无法构建或运行。

ℹ️ 细节

使用强制收缩包，Luke!

通常情况下，一个npm包在安装时只定义它的直接依赖关系和它们的版本范围，npm包管理器会在安装时解决所有横向依赖关系的版本。随着时间的推移，依赖关系的解析版本会有所不同，因为新的直接依赖关系和交叉依赖关系会发布新的版本。

尽管语义版本学（Semantic Versioning）已被维护者广泛接受，但众所周知，对于一个正在安装的普通软件包来说，npm会引入许多依赖关系，这就增加了一个软件包引入可能破坏你的应用的变化的风险。

使用npm-shrinkwrap.json 的反面是你强加给消费者的安全影响。被安装的依赖关系被钉在特定的版本上，所以即使这些依赖关系的较新版本被发布，它们也不会被安装。这就把责任推给了你，即维护者，让你在依赖关系中保持最新的安全修复，并定期发布CLI应用程序的安全更新。考虑使用Snyk依赖性升级来自动修复整个依赖性树的安全问题。完全公开：我是Snyk的一个开发者倡导者。

参考资料。

• 你真的知道yarn和npm包的lockfile是如何工作的吗？
• Yarn文档。锁文件应该被提交到版本库吗？

2.3 清理配置文件

✅ **做：**当CLI应用程序被卸载时，清理配置文件。可选择的是，CLI应用程序可以提示你的用户保留配置文件，以便在下次安装时跳过重新初始化阶段，获得更好的用户体验。

**否则：**用户的文件系统可能包含无主的配置文件，以及CLI工具在安装时引入的可识别数据等形式的残留物。

ℹ️ 细节

正如在有状态数据部分提到的，如果你的CLI应用程序使用持久性存储，例如保存配置文件，那么CLI应用程序也应该负责在它被卸载时删除其配置文件。

你可以使用NPMspre 或post 卸载脚本来达到这个目的。你可以在这个资源库中找到一个工作实例。

3 互操作性

本节涉及到使你的Node.js CLI与其他命令行工具无缝集成的最佳实践，并遵循CLI操作的自然惯例。

本节回答了以下问题。

• 我可以导出这个CLI的输出以方便解析吗？
• 我是否可以将这个CLI的输出管道到另一个命令行工具的输入？
• 我可以把另一个工具的结果输送给这个CLI吗？

在本节中。

• 3.1接受输入为STDIN
• 3.2启用结构化输出
• 3.3跨平台的礼节
• 3.4支持配置优先级

3.1 接受输入为STDIN

✅ **做：**对于需要处理数据的命令行应用程序，要让用户很容易将数据输送到标准输入（STDIN）。

**否则：**其他的命令行程序将不能提供他们的结果，直接作为你的CLI的输入，这将防止常见的UNIX单行语，如：。

$ curl -s 

ℹ️ 细节

如果命令行应用程序对数据进行处理，比如对通常用--file <file.json> 命令行参数指定的JSON文件执行某种任务。

一个基于官方Node.js API docs的for readline模块如何从命令管道中获取输入的例子，如下所示。

const

然后用管道将输入输入到上述Node.js应用程序中。

echo

3.2 启用结构化输出

✅ **做：**启用一个标志，以允许应用程序的结果的结构化输出，如果有这样的结果，以使解析和容易操作的数据。

**否则：**CLI的用户可能需要应用复杂的regex解析和匹配技术来提取由你的CLI提供的输出数据。

ℹ️ 细节

对于命令行应用程序的用户来说，解析数据并对其执行其他任务通常是非常有用的，例如使用它来提供网络仪表板，或电子邮件通知。

能够轻松地从命令行输出中提取感兴趣的数据，为你的CLI用户提供了更友好的体验。

3.3 跨平台礼节

✅ **做：**如果期望CLI能够跨平台运行，就必须对命令外壳的语义和文件系统等组件给予适当的关注，同时开发人员要利用相关的编程结构。

否则，CLI会由于诸如不正确的路径分隔符等因素而在其他操作系统上发生故障，即使代码中没有功能上的差异。

ℹ️ 细节

即使从程序的角度来看，功能并没有被剥离，而且在不同的操作系统中_应该_执行得很好，但一些遗漏的细微差别可能会使程序无法运行。让我们来探讨几个必须遵守跨平台伦理的案例。

错误地催生一个命令

你可能需要催生一个运行Node.js程序的进程。例如，你有以下脚本。

program.js

#!/usr/bin/env node

这个可以。

const cliExecPath = 'program.js'
const process = childProcess.spawn(cliExecPath, [])

这是更好的。

const cliExecPath = 'program.js'
const process = childProcess.spawn('node', [cliExecPath])

为什么它更好？program.js 源代码以类似 Unix 的Shebang符号开始，然而由于 Shebang 不是跨平台标准，Windows 不知道如何解释这个符号。

这对于package.json 脚本也是如此。考虑一下下面这种定义npm运行脚本的坏做法。

"scripts": {
  "postinstall": "myInstall.js"
}

这是由于myInstalls.js 中的Shebang不会帮助Windows理解如何用node 解释器运行这个。

相反，请遵循以下最佳做法。

"scripts": {
  "postinstall": "node myInstall.js"
}

Shell解释器各不相同

在不同的shell解释器中，并不是所有的字符都得到相同的处理。

例如，Windows命令提示符对单引号和双引号的处理不一样，就像在bash shell上所期望的那样，所以它不能识别单引号内的整个字符串属于同一个字符串组，这将导致错误。

这在使用Windows命令提示符的Windows Node.js环境中会失败。

package.json

"scripts": {
  "format": "prettier-standard '**/*.js'",
  ...
}

为了解决这个问题，使这个npm run 脚本确实会在Windows、macOS和Linux之间跨平台。

package.json

"scripts": {
  "format": "prettier-standard \"**/*.js\"",
  ...
}

在这个例子中，我们不得不使用双引号，并用JSON符号来转义它们。

避免串联路径

不同平台上的路径构建方式不同。当它们通过串联字符串手动构建时，它们在不同的平台之间必然不具有互通性。

让我们看看下面这个坏习惯的例子。

const

它假定正斜杠是路径分隔符，而在Windows中，例如，使用的是反斜杠。

与其手动构建文件系统路径，不如交给Node.js自己的path模块来做。

const

避免用分号串联命令

众所周知，Linux shells支持分号(;)来连接命令，以便按顺序运行，例如：cd /tmp; ls 。然而，在Windows上做同样的事情会失败。

避免做以下事情。

const

相反，使用双安培号或双管道符号。

const

3.4 支持配置优先级

✅ **做：**允许从多个来源获得配置，按优先级顺序。命令行参数的优先级最高，其次是shell变量，然后是不同级别的配置。

**否则：**用户在定制他们的CLI体验时面临挫折。

ℹ️ 细节

检测并支持使用环境变量的配置设置，因为这将是许多工具链中修改所调用的CLI应用程序行为的常见方式。

命令行应用程序的配置优先顺序应遵循以下几点。

• 当应用程序被调用时指定的命令行参数。
• 生成的shell的环境变量，以及应用程序可用的任何其他环境变量。
• 项目范围配置，例如：本地目录.git/config 文件。
• 用户范围配置，例如：用户的主目录配置文件：~/.gitconfig 或其XDG等同文件：~/.config/git/config 。
• 系统范围配置，例如：/etc/gitconfig 。

参考项目。

• cosmiconfig

4 可访问性

本节讨论的是使希望使用Node.js CLI应用程序，但缺乏维护者设计该应用程序的环境的用户可以使用该应用程序的最佳实践。

在本节中。

• 4.1容器化CLI
• 4.2优雅降级
• 4.3Node.js版本兼容
• 4.4Shebang自动检测Node.js的运行时间

4.1 容器化CLI

✅ **做：**为CLI创建一个docker镜像，并将其发布到像Docker Hub这样的公共注册中心，以便没有Node.js环境的用户可以使用它。

**否则：**没有Node.js环境的用户将没有npm 或npx ，因此将无法运行你的CLI应用程序。

ℹ️ 详细信息

从npm注册表安装Node.js CLI应用程序通常会使用Node.js本地工具链，如npm 或npx 。这些都是JavaScript和Node.js开发者常用的，而且预计会在安装说明中被引用。

然而，如果你的目标是让普通大众使用CLI应用程序，无论他们是否熟悉JavaScript，或者是否有这种工具，那么仅以npm注册表的安装形式分发你的CLI应用程序将受到限制。如果你的CLI应用程序打算在构建或CI环境中使用，那么这些可能还需要安装Node.js相关的工具链依赖项。

有很多方法来打包和分发可执行文件，而将其作为Docker容器，预先与你的CLI应用程序捆绑在一起，是一个容易消耗的替代方案，并且无依赖性（除了需要Docker环境之外）。

4.2 优雅降级

✅ **做：**为用户提供在不支持的环境中选择不使用彩色和富含动画的显示的能力，例如跳过交互性并以JSON的形式提供格式化的输出。

**否则：**对于没有支持的终端的用户来说，拥有彩色输出、使用终端互动，如提示和其他丰富的显示界面，可能会大大降低最终用户的体验，使他们不愿意使用你的CLI应用程序。

ℹ️ 细节

在终端和强大的提示机制上提供丰富的终端显示形式，如彩色输出、ascii图表、甚至动画，是很常见的。这些对于那些拥有支持的终端的人来说，可能有助于获得良好的用户体验，然而对于那些没有支持的人来说，它可能会显示乱码或完全无法操作。

为了使不支持终端的用户能够正确使用Node.js CLI应用程序，你可以选择。

• 自动检测终端能力，并在运行时评估是否降低CLI的交互性
• 提供一个选择，让用户明确地切换一个优雅的退化，例如通过提供一个--json 命令行参数来强制它输出原始数据。

?  Tip

  Supporting graceful degradation such as JSON output isn't only useful for
  end-users and their unuspported terminals, but is also valuable for running
  in continuous integration environments, as well as enabling users
  the ability to connect your program's output with other program's input or
  export data if needed.

4.3 Node.js版本兼容性

✅ **做：**针对支持和维护的Node.js版本。

**否则：**试图与旧的和不支持的Node.js版本保持兼容的代码库将难以维护，并失去语言和运行时特性的好处。

ℹ️ 细节

有时可能需要特别针对缺少ECAMScript新功能的旧Node.js版本。例如，如果你正在构建一个主要面向DevOps或IT的Node.js CLI，他们可能没有一个理想的Node.js环境和最新的运行时。作为参考，Debian Stretch (oldstable)搭载了Node.js 8.11.1。

如果你确实需要针对旧版本的Node.js，如Node.js 8、6或4，这些都是终结版，最好使用一个转译器，如Babel，以确保生成的代码符合V8 JavaScript引擎的版本和这些版本的Node.js运行时间。

另一个变通方法是提供CLI的容器化版本，以避免旧目标。见第（4.1）节 容器化CLI。

不要为了使用与未维护或EOL Node.js版本相匹配的旧ECMAScript语言规范而使你的程序代码变笨，因为这只会导致代码维护问题。

如果CLI被调用i一个不支持的环境，尝试检测它并以描述性的错误信息退出，以呈现一个友好和信息的错误信息。请看这个dockly的例子。

4.4 Shebang自动检测Node.js的运行时间

✅ **做：**在你的Shebang声明中使用一个与安装无关的引用，根据运行环境自动定位Node.js的运行时间，例如#!/usr/bin/env node 。

**否则：**使用硬编码的Node.js运行时位置，如#!/usr/local/bin/node ，这只针对你自己的环境，可能会使Node.js CLI在其他Node.js位置不同的环境中无法操作。

ℹ️ 细节

开发Node.js CLI可能是一个简单的开始，通过运行入口文件node cli.js ，随后在cli.js 文件的顶部添加#!/usr/local/bin/node ，然而后者仍然是一个有缺陷的方法，因为node 可执行文件的位置对于其他用户的环境是无法保证的。

应该注意的是，指定#!/usr/bin/env node 为最佳做法，仍然是假设Node.js运行时被引用为node ，而不是nodejs 或其他。

5 测试

在这一节中。

• 5.1不信任locales

5.1 不信任locales

✅ **做：**不要假设输出文本与你断言的字符串相等，因为测试可能会在与你的语言不同的系统上运行，或者是英语的默认语言。

**否则：**开发人员会遇到测试失败的情况，因为他们在与英语默认情况不同的系统上测试。

ℹ️ 细节

当你选择通过运行CLI和解析输出来测试CLI时，你可能倾向于grep特定的功能，以确保它们存在于输出中，例如当CLI运行时没有参数，正确地提供例子。

const

当测试将在不是基于英语的locales上运行时，如果你的CLI参数解析库支持自动检测locales并采用到它，那么像这样的测试将失败，由于语言从Examples 到相当于本地的语言被设置为系统中的默认locale。

6 误差

本节涉及的最佳实践涉及到使希望使用Node.js CLI应用程序的用户能够使用该应用程序，但缺乏维护者设计该应用程序的理想环境。

从本质上讲，本节所阐述的最佳实践的目标是帮助用户快速、轻松地排除错误，而不需要查阅文档或源代码来理解错误。

在本节中。

• 6.1可追踪的错误
• 6.2可操作的错误
• 6.3提供调试模式
• 6.4正确使用退出代码
• 6.5不费吹灰之力的错误报告

6.1 可追踪的错误

✅ **做：**当报告错误时，提供可追踪的错误代码，可以在项目的文档中查找，并简化错误信息的故障排除。

如果可能的话，用进一步的信息来扩展可追踪的错误代码，这样这些代码就可以很容易地被解析，而且上下文也很清楚。

❌ **否则：**通用的错误信息往往是模糊的，使用户很难搜索到解决方案。解析和分析并不那么直接，在文档中引用它们也不那么干净。

ℹ️ 细节

确保在返回错误信息时，包括一个参考号码或具体的错误代码，以便以后可以查询。就像HTTP状态代码一样，CLI应用也需要命名或编码的错误。

例子。

$ my-cli-tool --doSomething

Error (E4002): please provide an API token via environment variables

6.2 可操作的错误

✅ **做：**一个失败的错误信息应该告诉用户需要什么作为修复，而不是抱怨有一个错误。

**否则：**用户在面对错误信息时，如果没有提示解决错误的行动，可能无法成功使用你的CLI应用。

ℹ️ 详情

例子。

$ my-cli-tool --doSomething

Error (E4002): please provide an API token via environment variables

6.3 提供调试模式

✅ **做：**如果需要诊断问题，允许高级用户启用更详细的信息。

**否则：**不要跳过调试功能。这将更难收集用户的反馈，也更难让他们找出错误的原因。

ℹ️ 细节

使用环境变量和命令行参数来启用扩展的debug verbosity级别。 在你的代码中有意义的地方，植入debug信息，以帮助用户和维护者了解程序流程、输入和输出以及其他信息，使问题的解决更加容易。

? 推荐的软件包

参考开源Node.js软件包。

• debug

6.4 正确使用退出代码

✅ **做到：**用正确的退出代码来终止你的程序，这些代码传达了错误或退出状态的语义。

**否则：**不正确的或缺失的退出代码将阻碍你的CLI在持续集成流程和其他命令行脚本用例中的使用。

ℹ️ 细节

命令行脚本经常利用shell的$? ，来推断程序的状态代码，并根据它采取行动。这在持续集成（CI）流程中也被利用来确定一个步骤是否成功完成。

如果你的CLI总是在没有特定状态代码的情况下终止，甚至在错误时也是如此，那么shell和其他依赖它的程序就没有办法知道这一点。当一个错误发生，导致你的程序终止时，你应该传达这个意思。比如说。

try

退出代码的简短参考。

• 退出代码0表示成功执行
• 退出代码1表达了一个失败。

你也可以选择使用带有你的程序语义的自定义退出代码，但如果你这样做，一定要正确记录它们。

参考。BASH shell使用的退出代码列表

6.5 不费吹灰之力的错误报告

✅ **做到：**通过提供一个打开问题的URL，并尽可能地预置所需的数据，使提交错误报告成为一件容易的事情。问题模板，如GitHub，可以进一步指导用户哪些信息是必要的。

**否则：**用户在搜索如何报告错误时感到沮丧，最终可能得不到什么有用的信息，或者根本就不提交问题。

7 开发

本节涉及构建Node.js命令行应用程序的开发和维护最佳实践。

在本节中。

• 7.1使用bin对象
• 7.2使用相对路径
• 7.3使用文件字段

7.1 使用bin对象

✅ **做：**使用一个对象来定义可执行文件的名称和它的路径。

**否则：**你将会把包的名字和可执行文件耦合在一起。

ℹ️ 细节

下面的package.json 显示了一个将可执行文件的名称与文件名及其在项目中的位置脱钩的例子。

7.2 使用相对路径

✅ **做：**使用process.cwd() 来访问用户输入路径，使用__dirname 来访问基于项目的路径。

**否则：**你将得到不正确的文件路径，并且无法访问文件。

ℹ️ 细节

你可能会发现自己需要访问项目文件范围内的文件，或访问由用户输入的文件，如日志、JSON文件或其他文件。混淆使用process.cwd() 或__dirname ，会导致错误，也会导致不使用这两种方法。

如何正确访问文件。

• process.cwd() ：当你需要访问的文件路径取决于Node.js CLI的相对位置时，可以使用它。这方面的一个很好的例子是，当CLI支持文件路径来创建日志时，例如：myCli --outfile ../../out.json 。如果myCli 安装在/usr/local/node_modules/myCli/bin/myCli.js ，那么process.cwd() 将不会指向该位置，而是指向当前工作目录，即用户在调用CLI时所在的任何目录。
• __dirname ：当你需要从CLI的源代码中访问一个文件，并从该代码所在文件的相关位置引用一个文件时，可以使用它。例如，当CLI需要访问另一个目录中的JSON数据文件时：fs.readFile(path.join(__dirname, '..', 'myDataFile.json')) 。

7.3 使用files 字段

✅ **做：**使用files 字段，在你发布的包中只包括必要的文件。

**否则：**你将会得到一个包含可能不需要运行你的CLI应用程序的文件的包。例如（测试文件、开发配置等）。

ℹ️ 详细信息

为了保持发布的软件包体积小，我们应该只包括运行CLI应用程序所需的文件。更多细节请见本帖。

下面的files 字段告诉npm CLI包括src目录下的所有文件，除了spec文件。

"files"

作者

Node.js CLI应用程序最佳实践©Liran Tal, 在CC BY-SA 4.0许可下发布。

本项目遵循所有贡献者的规范。欢迎任何形式的贡献!

许可证

本作品采用知识共享署名-相同方式共享4.0国际许可协议进行许可。