<a href="https://nodejs-security.com">
  <img alt="Node.js Security" align="center" src="https://img.shields.io/badge/%F0%9F%A6%84-Learn%20Node.js%20Security%E2%86%92-gray.svg?colorA=5734F5&colorB=5734F5&style=flat" />
</a>

Learn Node.js Secure Coding techniques and best practices from <a href="https://www.lirantal.com">Liran Tal</a>

Node.js CLI 应用程序最佳实践

一个关于如何构建成功，富有同情心且用户友好的 Node.js 命令行界面（CLI）应用程序的精选最佳实践的集合。

为什么使用本指南？

一个糟糕的 CLI 会很轻易打断用户与其之间的交互。构建成功的 CLI 需要关注细节以及对用户的同理心，以便创造良好的用户体验。这非常容易出错。 在本指南中，我整理了一个重点领域的最佳实践列表，旨在优化与 CLI 应用程序交互时的理想用户体验。 这很容易出错

在本指南中，我整理了一个重点领域的最佳实践列表，目的是在优化与 CLI 应用程序交互时的理想用户体验。

特点:

• 🤖 AI agents ready SKILL.md file
• ✅ 37 best practices for building successful Node.js CLI applications
• 🗣️ Localized across multiple languages - read in a different language: 🇨🇳, 🇪🇸, or help translate to other languages. Suggest new languages.
• 🙏 欢迎贡献

为什么是我？

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

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

Dockly 用于管理 docker 容器和服务的沉浸式终端界面

npq safely install packages with npm/yarn by auditing them as part of your install process

lockfile-lint 创建 npm 或 yarn 锁定文件以分析和检测安全问题

is-website-vulnerable 在网站的前端 JavaScript 库中查找已知的安全漏洞

该团队 ✨

感谢这些优秀的人们(表情符号键 ):

Vanilla 🌍

Terkel 🖋

Jason Karns 🖋

Dave Sag 🚧

José J. Pérez Rivas 🌍

Sureshraj 🖋

---

目录

• 1 命令行体验
• 1.1 遵守 POSIX 参数
• 1.2 构建富有同理心的 CLI
• 1.3 有状态数据
• 1.4 提供富有色彩的体验
• 1.5 丰富的交互
• 1.6 无处不在的超链接
• 1.7 零配置
• 1.8 遵守 POSIX 信号
• 2 分发
• 2.1 选择占用较小的依赖项
• 2.2 使用 shrinkwrap, Luke
• 2.3 清理配置文件
• 3 互通性
• 3.1 接受 STDIN 输入
• 3.2 启用结构化输出
• 3.3 跨平台规范
• 3.4 支持配置优先
• 4 辅助功能
• 4.1 容器化 CLI
• 4.2 优雅降级
• 4.3 Node.js 版本兼容性
• 4.4 Shebang 自动检测 Node.js 运行时
• 5 测试
• 5.1 不信任语言环境
• 6 错误
• 6.1 可追踪的错误
• 6.2 可行性错误
• 6.3 提供调试模式
• 6.4 正确使用退出代码
• 6.5 轻松的错误报告
• 7 开发
• 7.1 使用 bin 对象
• 7.2 使用相对路径
• 7.3 使用 files 字段
• 8 分析
• 8.1 严格选择加入分析
• 9 Versioning
• 9.1 Include a --version Flag
• 9.2 Use Semantic Versioning
• 9.3 Provide Version Information in a 'package.json' file
• 9.4 Display Version in Error Messages and Help Text
• 9.5 Backward Compatibility
• 9.6 Publish Versioned Releases on npm
• 9.7 Update Your App's Version Documents
• 10 Security
• 10.1 Minimize Argument Injection
• 11 Appendix: CLI Frameworks
• 11.1 CLI Frameworks Table
• 12 Appendix: CLI educational resources

---

1 命令行体验

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

在本节中：

• 1.1 遵守 POSIX 参数
• 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 编码标准).
• options specified using the short form singular - may contain one alphanumeric character.
• 指定多个没有值的选项可以进行分组，例如 myCli -abc 等效于 myCli -a -b -c。

命令行高级用户希望您的命令行应用程序具有与其他 Unix 应用程序类似的约定。

📦 推荐的软件包

对开源 Node.js 包的参考：

• commander
• yargs
• Optique

1.2 构建富有同理心的 CLI

✅ 可行: 将工作流放置在适当的位置，以帮助用户成功与 CLI 进行交互，否则将导致错误和挫败感。

❌ 否则: 如果不能在支持用户方面提供可操作的帮助，将会因为缺乏操作 CLI 的能力而导致受挫。

ℹ️ 详情

一个程序的命令行界面与 web 用户界面没有什么不同，因为您可以按照程序作者的意愿完成尽可能多的工作，以确保它被成功地使用。

通过构建支持代入用户感受的 CLI 来优化成功的交互。 作为一个例子，让我们研究一下 curl 程序期望 URL 作为其主要数据输入，而用户未能提供它的情况。 此类失败将导致阅读（希望）描述性错误消息或查看 curl --help 输出。 然而，考虑用户感受的 CLI 会呈现一个交互式提示来捕获用户的输入，从而实现成功的交互。

1.3 状态数据

✅ 可行: 在 CLI 应用程序的多次调用之间提供有状态的体验，并记住值和数据以提供无缝交互。

❌ 否则: 要求您的用户在多次调用 CLI 时重复提供相同的信息会惹恼您的用户。

ℹ️ 详情

你可能发现自己需要为你的 CLI 应用程序提供存储持久性。 例如记住用户名、电子邮件、API令牌或多次使用 CLI 之间的其他首选项。 使用配置助手，允许应用程序持续使用此用户设置。 在阅读/写入文件时请务必遵循 XDG 基础目录规格 (或选择一个尊重该数据的配置助理)。 这使用户能够控制文件的编写和管理位置。

参考项目：

• configstore
• conf

1.4 提供富有色彩的体验

✅ 可行： 在 CLI 应用程序中使用颜色来突出显示应用程序输出的部分内容，并提供优雅的降级或颜色检测，以允许自动退出，以免输出出现乱码。 通过 CLI 选项、环境变量和/或配置文件确保手动选入和退出是可以的。

❌ 否则: 苍白的程序输出中可能容易丢失信息，尤其是当输出文本繁重的时候。

ℹ️ 详情

大多数今天用于与命令行应用程序交互的终端支持颜色文本，例如由特制的 ANSI 编码的字符开启。

您的命令行应用程序输出中的彩色显示可能会进一步促进更丰富的体验和增强互动。 尽管如此，不受支持的终端可能会在屏幕上以累赘信息的形式出现退化的输出。 此外，CLI 可能被用于不支持彩色输出的持续集成构建作业。 如今，大多数用于与命令行应用程序交互的终端都支持彩色文本，例如通过特制 ANSI 编码字符启用的文本。 命令行应用程序输出中的彩色显示可能会进一步促进更丰富的体验和更多的交互。也就是说，不受支持的终端可能会经历屏幕上乱码信息形式的输出降级。此外，CLI 可以在可能不支持彩色输出的持续集成构建作业中使用。即使在构建服务器之外，也可以通过 IDE 的控制台使用 CLI，该控制台可能无法处理某些字符。必须可以手动选择退出。

📦 推荐的软件包

对开源 Node.js 包的参考：

• built-in { styleText } from 'node:util'
• chalk
• colors
• kleur

1.5 丰富的交互

✅ 可行: 除了文本输入提示符之外，还可以利用丰富的命令行交互为 CLI 用户提供更流畅的体验。

❌ 否则: 当数据是以封闭选项(即下拉菜单)的形式出现时，作为输入的文本提示可能对用户来说很麻烦。

ℹ️ 详情

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

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

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

📦 推荐的软件包

对开源 Node.js 包的参考：

• enquirer
• ora
• ink
• prompts

1.6 无处不在的超链接

✅ 可行: 在文本输出中为两个 URL 使用格式正确的超链接 (e.g: https://www.github.com), 以及源代码 (e.g: src/Util.js:2:75) - 现代终端能够将这两者转换为可点击的链接。

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

ℹ️ 详情

如果您分享指向 URL 的链接，或者指向某个文件以及该文件中的特定行号和列，则可以提供指向这两个示例的格式正确的链接，一旦单击这些链接，就会在浏览器或 IDE 定义的位置打开。

参考项目：

• open

1.7 零配置

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

❌ 否则: 如果可以用可靠的方式自动检测命令行参数，并且调用的操作不显式要求用户交互（例如确认删除），则不要强制用户交互。

ℹ️ Details

目的是在运行 CLI 应用程序时提供「开箱即用」的体验。 例如， POSIX定义了用于不同用途的环境变量配置 的标准。 例如： TMPDIR, NO_COLOR, DEBUG, HTTP_PROXY 和其他。 自动检测这些并在必要时提示确认。

围绕零配置构建的参考项目：

• Jest JavaScript 测试框架
• Parcel, Web 应用程序打包工具

1.8 遵守 POSIX 信号

✅ 可行: 确保您的程序遵守 POSIX 信号 以使其能够与用户或其他程序正确交互。

❌ 否则: 您的程序不能与其他程序很好地配合，并会引入意外的行为。

ℹ️ 详情

尤其是对于 CLI 应用程序，与用户输入交互是很常见的，如果管理不当，可能会导致您的应用程序无法响应 SIGINT 中断，用户在按下 CTRL+C 键时通常会使用 SIGINT 中断。

不遵守进程信号的问题在由非人之间的互动引导下来时更加严重。 例如，在 Docker 容器中运行但不会响应发送给它的软件中断信号的 CLI。

2 分发

本节介绍了有关以最佳方式分发和打包 Node.js 命令行应用程序的最佳实践，供消费者使用。

在本节中：

• 2.1 选择占用较小的依赖项
• 2.2 使用 shrinkwrap, Luke
• 2.3 清理配置文件

2.1 选择占用较小的依赖项

✅ 可行: 最大限度地减少生产依赖项的使用，使用较小的替代依赖项，并审查依赖项的覆盖范围以及传递性依赖项，以确保 Node.js CLI 的小捆绑。 在这个问题上保持平衡，注意不要通过重开轮来过度优化对依赖的使用