15.4 命令行工具（CLI）开发原理与实践

作为 Node.js 开发者，除了编写 Web 服务、脚本之外，我们也经常需要创建一些命令行工具来提升日常开发效率。比如我们每天都在使用的 npm、yarn、eslint、prettier，它们本质上都是由 Node.js 编写的命令行程序。掌握 CLI 开发的基本原理和流程，不仅能让你打造团队通用的自动化工具，还能加深你对 Node.js 运行机制的理解。

15.4.1 CLI 工具的底层原理

命令行工具本质上就是一个可以全局安装（或通过 npx 临时运行）的可执行 Node.js 脚本。一切的核心都围绕着 让操作系统能够把这个脚本当作一个命令来调用 展开，这需要解决两个核心问题：

注册为全局命令：让系统知道，当用户在终端输入 mycli 时，应该执行一个特定的 JavaScript 文件。
用 Node.js 执行该文件：系统如何将 .js 文件交给 Node.js 解释器去运行。

shebang（#!）行

任何可执行的 Node.js 脚本文件的第一行，通常都会添加这样一行代码：

#!/usr/bin/env node

它的作用是告诉操作系统：用 node 程序来解释执行这个脚本。/usr/bin/env node 会从环境变量 PATH 中寻找第一个可用的 node 命令，这让脚本在不同系统上都具备可移植性，即使 Node.js 安装在非标准路径下也能正常运行。

package.json 的 `bin` 字段

仅有 shebang 行还不够。要让一个命令 mycli 指向你的脚本 bin/cli.js，需要用 package.json 中的 bin 字段进行注册：

{
  "name": "mycli",
  "version": "1.0.0",
  "bin": {
    "mycli": "./bin/cli.js"
  }
}

上面的配置表示：当用户全局安装 mycli 包时，npm 会在系统的 PATH 可执行目录下创建一个名为 mycli 的符号链接（Windows 下为一个 .cmd 包装脚本），该链接指向 ./bin/cli.js。

如果你只想注册一个与包名相同的命令，也可以简写为：

{
  "name": "mycli",
  "bin": "./bin/cli.js"
}

这样安装后，用户就能直接运行 mycli 命令了。本地开发时，可以使用 npm link 将这个包链接到全局，从而在任意目录测试该命令。

全局安装与本地的 `npx`

全局安装：npm install -g mycli，将 mycli 当作一个全局命令使用。
直接使用 npx：npx mycli 会临时下载 mycli 包并执行，无需全局安装，尤其适合一次性工具或 CI 环境。

15.4.2 基础实践：从零搭建一个 CLI

下面我们通过一个名为 file-stat 的简单工具，展示 CLI 开发的完整流程。这个工具接收一个文件路径作为参数，输出文件的大小、修改时间等信息。

1. 初始化项目结构

mkdir file-stat
cd file-stat
npm init -y

修改 package.json，增加 bin 字段：

{
  "name": "file-stat",
  "version": "1.0.0",
  "bin": {
    "file-stat": "./bin/cli.js"
  }
}

2. 编写入口脚本 `bin/cli.js`

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

// 获取命令行参数
const filePath = process.argv[2];

if (!filePath) {
  console.error('请指定文件路径：file-stat <文件>');
  process.exit(1);
}

const absolutePath = path.resolve(filePath);

fs.stat(absolutePath, (err, stats) => {
  if (err) {
    console.error(`无法读取文件：${err.message}`);
    process.exit(1);
  }

  console.log(`文件：${absolutePath}`);
  console.log(`大小：${(stats.size / 1024).toFixed(2)} KB`);
  console.log(`创建时间：${stats.birthtime.toLocaleString()}`);
  console.log(`最后修改：${stats.mtime.toLocaleString()}`);
});

3. 本地链接测试

在项目根目录执行：

npm link

之后就可以在任意目录运行 file-stat <文件> 来测试功能。

$ file-stat ./package.json
文件：/Users/me/file-stat/package.json
大小：0.34 KB
创建时间：2025-01-15 09:30:00
最后修改：2025-01-15 09:30:00

这样就完成了一个最精简的 CLI 工具。但它还很原始：参数解析全靠数组手动提取，没有帮助信息，没有子命令，当参数变多时极难维护。

15.4.3 进阶：使用成熟库提升开发效率

真实项目中的 CLI 会包含复杂的参数解析、子命令、交互式问答、加载动画等功能。社区提供了很多优秀的库来简化这些工作，下面介绍三个最核心的工具。

commander —— 命令行参数解析

commander.js 是 Node.js 生态中最为流行的命令行接口库。它提供链式 API 定义选项、参数和子命令，还能自动生成帮助信息。

改造 file-stat，使用 commander：

先安装依赖：

npm install commander

修改 bin/cli.js：

#!/usr/bin/env node

const { Command } = require('commander');
const fs = require('fs');
const path = require('path');

const program = new Command();

program
  .name('file-stat')
  .description('显示文件信息')
  .version('1.0.0')
  .argument('<filePath>', '要查看的文件路径')
  .option('-u, --human', '以人类可读格式显示大小')
  .action((filePath, options) => {
    const abs = path.resolve(filePath);
    fs.stat(abs, (err, stats) => {
      if (err) {
        console.error(`错误：${err.message}`);
        process.exit(1);
      }
      const size = options.human
        ? `${(stats.size / 1024).toFixed(2)} KB`
        : `${stats.size} 字节`;
      console.log(`文件：${abs}`);
      console.log(`大小：${size}`);
      console.log(`修改时间：${stats.mtime.toLocaleString()}`);
    });
  });

program.parse();

现在 file-stat --help 会自动输出清晰的帮助信息；file-stat -u ./README.md 则会显示可读大小。对于更复杂的场景，commander 还支持子命令（.command()），可以构建像 docker run、git commit 这类具有层级结构的 CLI。

inquirer —— 交互式命令行

inquirer.js 用于创建交互式问答、列表选择、确认框等，是搭建初始化脚手架（如 create-react-app）的关键库。

例如，我们可以做一个简易的项目初始化向导：

const inquirer = require('inquirer');

async function askQuestions() {
  const answers = await inquirer.prompt([
    { type: 'input', name: 'name', message: '项目名称：', default: 'my-app' },
    { type: 'list', name: 'template', message: '选择模板：', choices: ['React', 'Vue', 'Node'] },
    { type: 'confirm', name: 'useGit', message: '是否初始化 Git？', default: true },
  ]);
  console.log('配置结果：', answers);
}

askQuestions();

运行时会动态交互，引导用户完成配置，大大提升了 CLI 工具的易用性。

chalk 与 ora —— 美化输出与加载动画

chalk 用于为终端输出添加颜色和样式，ora 则提供优雅的 loading 旋转动画。

const chalk = require('chalk');
const ora = require('ora');

console.log(chalk.green('成功！'));
console.log(chalk.red.bold('错误信息'));

const spinner = ora('处理中...').start();
setTimeout(() => {
  spinner.succeed('完成了');
}, 2000);

结合这些库，你的 CLI 工具就能拥有和生态内知名工具一样友好、专业的用户体验。

15.4.4 发布与分享 CLI 工具

开发完成后，你可以将工具发布到 npm，让其他开发者通过 npm install -g <包名> 快速安装使用。发布流程与普通 npm 包完全一致：

确保 package.json 正确：包含 bin 字段，以及 keywords、description 便于搜索。
测试：在本地通过 npm link 充分测试。
注册 npm 账号并登录：npm login。
发布：在项目根目录执行 npm publish。建议首次发布前使用 npm publish --dry-run 预览将要上传的文件。
版本迭代：遵循语义化版本，使用 npm version patch/minor/major 更新版本并打 tag。

如果你的包是作用域包（如 @mycompany/file-stat），发布时需要加上 --access public 参数。

15.4.5 实践总结与设计建议

开发 CLI 工具时，有几个设计原则值得一提：

默认行为要合理：最简调用 mycli 应该产生有意义的默认输出或提示，而不是报错。
提供清晰帮助：利用 commander 自动生成 --help，描述每个参数的含义，必要时给出示例。
遵循 Unix 哲学：组合简单命令完成复杂任务。一个 CLI 工具应该只做好一件事。
支持 --version：方便用户判断当前安装的版本。
处理好退出码：成功时 process.exit(0)，出错时 process.exit(1)，便于在 CI 流程中判断构建状态。
考虑平台兼容性：避免使用仅限 POSIX 或仅限 Windows 的系统调用，使用 path 模块处理路径，使用 cross-env 处理环境变量等。

从原理到实践，Node.js CLI 开发充分体现了 Node.js “轻量、高效、生态丰富” 的优势。掌握了这些技能，你就能把日常重复的劳动封装成可复用的命令，提升自己和团队的生产力。在后续的工程化章节中，我们还会看到如何在 Monorepo 中统一管理多个 CLI 工具，以及如何利用它们实现自动化 CI/CD 流水线。