Node.js CLI 工具开发

核心知识点

CLI 工具概述

CLI（Command Line Interface）工具是通过命令行界面与用户交互的程序，它可以执行各种任务，如文件操作、数据处理、系统管理等。Node.js 是开发 CLI 工具的理想选择，因为它具有跨平台特性、丰富的生态系统和简洁的语法。

CLI 工具的主要优势：

• 自动化：可以自动化执行重复任务
• 脚本化：可以编写脚本组合多个命令
• 跨平台：在不同操作系统上运行
• 高效：对于熟练用户，命令行操作比图形界面更高效
• 可集成：可以与其他工具和系统集成

CLI 工具的常见类型：

• 实用工具：如文件处理、数据转换工具
• 开发工具：如代码生成器、构建工具
• 管理工具：如系统管理、配置管理工具
• 应用工具：如应用的命令行接口

CLI 开发核心概念

1. 命令行参数：

   • 位置参数：按顺序传递的参数
   • 选项参数：以 - 或 -- 开头的参数
   • 标志参数：布尔值选项，如 --verbose

2. 命令结构：

   • 单命令工具：如 ls、cat
   • 多命令工具：如 git、npm，具有子命令

3. 交互式命令行：

   • 提示用户输入
   • 选择菜单
   • 进度显示
   • 颜色和样式

4. 文件操作：

   • 读取和写入文件
   • 文件系统遍历
   • 文件权限管理

5. 进程管理：

   • 执行子进程
   • 管道和流
   • 进程间通信

6. 错误处理：

   • 命令行错误处理
   • 退出码管理
   • 错误消息格式化

CLI 开发工具和库

1. 参数解析：

   • commander：命令行参数解析库，支持子命令
   • yargs：功能丰富的命令行参数解析库
   • minimist：轻量级命令行参数解析库

2. 交互式命令行：

   • inquirer：交互式命令行界面库
   • enquirer：现代化的交互式命令行库
   • prompt：简单的命令行提示库

3. 颜色和样式：

   • chalk：终端字符串样式库
   • colors：终端颜色库
   • ora：终端 spinner 库

4. 文件系统：

   • fs-extra：增强的文件系统操作库
   • glob：文件路径匹配库
   • rimraf：跨平台删除文件库

5. 工具库：

   • commander：命令行框架
   • execa：更好的子进程执行库
   • listr：任务列表库
   • boxen：终端盒子绘制库

6. 打包和发布：

   • pkg：将 Node.js 应用打包为可执行文件
   • nexe：将 Node.js 应用编译为可执行文件

实用案例分析

案例 1：基本 CLI 工具开发

问题：需要构建一个基本的 CLI 工具，能够解析命令行参数并执行相应的操作

解决方案：使用 commander 库构建基本的 CLI 工具。

实现步骤：

1. 初始化项目

mkdir my-cli-tool
cd my-cli-tool
npm init -y
npm install commander

2. 创建 CLI 入口文件

// bin/cli.js
#!/usr/bin/env node

const { Command } = require('commander');
const program = new Command();

// 定义版本和描述
program
  .version('1.0.0')
  .description('一个简单的 CLI 工具示例');

// 定义命令
program
  .command('greet')
  .description('向用户打招呼')
  .option('-n, --name <name>', '用户名称', '世界')
  .action((options) => {
    console.log(`你好，${options.name}！`);
  });

// 定义另一个命令
program
  .command('calculate')
  .description('执行简单的计算')
  .option('-a, --add <numbers>', '加法运算，用逗号分隔数字', (value) => value.split(',').map(Number))
  .option('-s, --subtract <numbers>', '减法运算，用逗号分隔数字', (value) => value.split(',').map(Number))
  .action((options) => {
    if (options.add) {
      const result = options.add.reduce((sum, num) => sum + num, 0);
      console.log(`加法结果: ${result}`);
    }
    if (options.subtract) {
      const result = options.subtract.reduce((diff, num, index) => index === 0 ? num : diff - num, 0);
      console.log(`减法结果: ${result}`);
    }
  });

// 解析命令行参数
program.parse(process.argv);

3. 配置 package.json

{
  "name": "my-cli-tool",
  "version": "1.0.0",
  "description": "一个简单的 CLI 工具示例",
  "bin": {
    "my-cli": "bin/cli.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "cli",
    "tool"
  ],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "commander": "^10.0.0"
  }
}

4. 测试 CLI 工具

# 链接到全局
npm link

# 测试版本
my-cli --version

# 测试帮助
my-cli --help

# 测试 greet 命令
my-cli greet
my-cli greet --name 张三

# 测试 calculate 命令
my-cli calculate --add 1,2,3,4,5
my-cli calculate --subtract 10,2,3

案例 2：交互式 CLI 工具开发

问题：需要构建一个交互式 CLI 工具，能够提示用户输入并根据输入执行操作

解决方案：使用 inquirer 库构建交互式 CLI 工具。

实现步骤：

1. 安装依赖

npm install inquirer chalk

2. 创建交互式 CLI 工具

// bin/interactive-cli.js
#!/usr/bin/env node

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

console.log(chalk.blue('欢迎使用交互式 CLI 工具！'));
console.log('');

// 交互式问题
const questions = [
  {
    type: 'input',
    name: 'name',
    message: '请输入你的名字:',
    default: '访客'
  },
  {
    type: 'list',
    name: 'action',
    message: '请选择要执行的操作:',
    choices: [
      { name: '创建文件', value: 'create' },
      { name: '读取文件', value: 'read' },
      { name: '删除文件', value: 'delete' }
    ]
  },
  {
    type: 'input',
    name: 'filename',
    message: '请输入文件名:',
    default: 'example.txt'
  },
  {
    type: 'confirm',
    name: 'confirm',
    message: '确定要执行此操作吗?',
    default: true
  }
];

// 处理用户输入
inquirer.prompt(questions).then((answers) => {
  console.log('');
  console.log(chalk.green('操作结果:'));
  console.log(`姓名: ${answers.name}`);
  console.log(`操作: ${answers.action}`);
  console.log(`文件名: ${answers.filename}`);
  console.log(`确认: ${answers.confirm}`);
  
  if (answers.confirm) {
    switch (answers.action) {
      case 'create':
        console.log(chalk.yellow('创建文件...'));
        // 这里可以添加实际的文件创建代码
        break;
      case 'read':
        console.log(chalk.yellow('读取文件...'));
        // 这里可以添加实际的文件读取代码
        break;
      case 'delete':
        console.log(chalk.yellow('删除文件...'));
        // 这里可以添加实际的文件删除代码
        break;
    }
    console.log(chalk.green('操作完成！'));
  } else {
    console.log(chalk.red('操作被取消！'));
  }
});

3. 配置 package.json

{
  "name": "interactive-cli",
  "version": "1.0.0",
  "description": "交互式 CLI 工具示例",
  "bin": {
    "interactive-cli": "bin/interactive-cli.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "cli",
    "interactive"
  ],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "chalk": "^5.0.0",
    "inquirer": "^9.0.0"
  }
}

4. 测试交互式 CLI 工具

# 链接到全局
npm link

# 运行交互式 CLI 工具
interactive-cli

案例 3：文件操作 CLI 工具开发

问题：需要构建一个文件操作 CLI 工具，能够执行文件的创建、读取、写入和删除操作

解决方案：使用 fs-extra 库构建文件操作 CLI 工具。

实现步骤：

1. 安装依赖

npm install fs-extra commander chalk

2. 创建文件操作 CLI 工具

// bin/file-cli.js
#!/usr/bin/env node

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

const program = new Command();

program
  .version('1.0.0')
  .description('文件操作 CLI 工具');

// 创建文件命令
program
  .command('create <file>')
  .description('创建新文件')
  .option('-c, --content <content>', '文件内容', '')
  .action((file, options) => {
    try {
      const filePath = path.resolve(file);
      fs.ensureFileSync(filePath);
      if (options.content) {
        fs.writeFileSync(filePath, options.content);
      }
      console.log(chalk.green(`文件创建成功: ${filePath}`));
    } catch (error) {
      console.error(chalk.red(`创建文件失败: ${error.message}`));
      process.exit(1);
    }
  });

// 读取文件命令
program
  .command('read <file>')
  .description('读取文件内容')
  .action((file) => {
    try {
      const filePath = path.resolve(file);
      if (!fs.existsSync(filePath)) {
        console.error(chalk.red(`文件不存在: ${filePath}`));
        process.exit(1);
      }
      const content = fs.readFileSync(filePath, 'utf8');
      console.log(chalk.blue('文件内容:'));
      console.log(content);
    } catch (error) {
      console.error(chalk.red(`读取文件失败: ${error.message}`));
      process.exit(1);
    }
  });

// 写入文件命令
program
  .command('write <file> <content>')
  .description('写入文件内容')
  .option('-a, --append', '追加内容', false)
  .action((file, content, options) => {
    try {
      const filePath = path.resolve(file);
      if (options.append) {
        fs.appendFileSync(filePath, content);
        console.log(chalk.green(`内容追加成功: ${filePath}`));
      } else {
        fs.writeFileSync(filePath, content);
        console.log(chalk.green(`内容写入成功: ${filePath}`));
      }
    } catch (error) {
      console.error(chalk.red(`写入文件失败: ${error.message}`));
      process.exit(1);
    }
  });

// 删除文件命令
program
  .command('delete <file>')
  .description('删除文件')
  .option('-f, --force', '强制删除', false)
  .action((file, options) => {
    try {
      const filePath = path.resolve(file);
      if (!fs.existsSync(filePath)) {
        if (options.force) {
          console.log(chalk.yellow(`文件不存在，跳过删除: ${filePath}`));
          return;
        }
        console.error(chalk.red(`文件不存在: ${filePath}`));
        process.exit(1);
      }
      fs.unlinkSync(filePath);
      console.log(chalk.green(`文件删除成功: ${filePath}`));
    } catch (error) {
      console.error(chalk.red(`删除文件失败: ${error.message}`));
      process.exit(1);
    }
  });

// 列出目录命令
program
  .command('list [dir]')
  .description('列出目录内容')
  .action((dir = '.') => {
    try {
      const dirPath = path.resolve(dir);
      if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
        console.error(chalk.red(`目录不存在: ${dirPath}`));
        process.exit(1);
      }
      const files = fs.readdirSync(dirPath);
      console.log(chalk.blue(`目录内容: ${dirPath}`));
      files.forEach((file) => {
        const filePath = path.join(dirPath, file);
        const stats = fs.statSync(filePath);
        const type = stats.isDirectory() ? chalk.green('[DIR]') : chalk.yellow('[FILE]');
        console.log(`${type} ${file}`);
      });
    } catch (error) {
      console.error(chalk.red(`列出目录失败: ${error.message}`));
      process.exit(1);
    }
  });

// 解析命令行参数
program.parse(process.argv);

3. 配置 package.json

{
  "name": "file-cli",
  "version": "1.0.0",
  "description": "文件操作 CLI 工具",
  "bin": {
    "file-cli": "bin/file-cli.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "cli",
    "file",
    "tool"
  ],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "chalk": "^5.0.0",
    "commander": "^10.0.0",
    "fs-extra": "^11.0.0"
  }
}

4. 测试文件操作 CLI 工具

# 链接到全局
npm link

# 测试创建文件
file-cli create test.txt --content "Hello, World!"

# 测试读取文件
file-cli read test.txt

# 测试写入文件
file-cli write test.txt "Hello, CLI!"

# 测试追加内容
file-cli write test.txt "\n追加内容" --append

# 测试列出目录
file-cli list

# 测试删除文件
file-cli delete test.txt

案例 4：多命令 CLI 工具开发

问题：需要构建一个多命令 CLI 工具，类似于 git 或 npm，具有多个子命令

解决方案：使用 commander 库构建多命令 CLI 工具。

实现步骤：

1. 创建多命令 CLI 工具

// bin/multi-cli.js
#!/usr/bin/env node

const { Command } = require('commander');
const chalk = require('chalk');

const program = new Command();

program
  .version('1.0.0')
  .description('多命令 CLI 工具示例');

// 子命令 1：用户管理
const userCommand = program.command('user')
  .description('用户管理命令');

userCommand
  .command('create <name> <email>')
  .description('创建新用户')
  .action((name, email) => {
    console.log(chalk.green(`创建用户: ${name} (${email})`));
  });

userCommand
  .command('list')
  .description('列出所有用户')
  .action(() => {
    console.log(chalk.blue('用户列表:'));
    console.log('1. 用户1 - user1@example.com');
    console.log('2. 用户2 - user2@example.com');
  });

userCommand
  .command('delete <id>')
  .description('删除用户')
  .action((id) => {
    console.log(chalk.red(`删除用户: ${id}`));
  });

// 子命令 2：项目管理
const projectCommand = program.command('project')
  .description('项目管理命令');

projectCommand
  .command('init <name>')
  .description('初始化新项目')
  .action((name) => {
    console.log(chalk.green(`初始化项目: ${name}`));
  });

projectCommand
  .command('list')
  .description('列出所有项目')
  .action(() => {
    console.log(chalk.blue('项目列表:'));
    console.log('1. 项目1');
    console.log('2. 项目2');
  });

// 全局选项
program
  .option('-v, --verbose', '启用详细输出')
  .hook('preAction', (command) => {
    if (command.parent.opts().verbose) {
      console.log(chalk.yellow('详细模式已启用'));
    }
  });

// 解析命令行参数
program.parse(process.argv);

// 处理未匹配的命令
if (!process.argv.slice(2).length) {
  program.outputHelp();
}

2. 配置 package.json

{
  "name": "multi-cli",
  "version": "1.0.0",
  "description": "多命令 CLI 工具示例",
  "bin": {
    "multi-cli": "bin/multi-cli.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "cli",
    "multi-command"
  ],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "chalk": "^5.0.0",
    "commander": "^10.0.0"
  }
}

3. 测试多命令 CLI 工具

# 链接到全局
npm link

# 测试帮助
multi-cli --help

# 测试用户命令
multi-cli user --help
multi-cli user create "张三" "zhangsan@example.com"
multi-cli user list
multi-cli user delete 1

# 测试项目命令
multi-cli project --help
multi-cli project init "新项目"
multi-cli project list

# 测试详细模式
multi-cli --verbose user list

案例 5：进度显示和高级交互

问题：需要构建一个具有进度显示和高级交互功能的 CLI 工具

解决方案：使用 ora、listr 等库构建具有进度显示和高级交互功能的 CLI 工具。

实现步骤：

1. 安装依赖

npm install ora listr chalk

2. 创建进度显示 CLI 工具

// bin/progress-cli.js
#!/usr/bin/env node

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

console.log(chalk.blue('进度显示 CLI 工具示例'));
console.log('');

// 单个进度显示
function singleProgress() {
  console.log(chalk.yellow('单个进度显示:'));
  
  const spinner = ora('正在执行任务...').start();
  
  setTimeout(() => {
    spinner.text = '任务执行中...';
  }, 1000);
  
  setTimeout(() => {
    spinner.succeed('任务执行成功！');
    console.log('');
    multiProgress();
  }, 3000);
}

// 多个任务进度显示
function multiProgress() {
  console.log(chalk.yellow('多个任务进度显示:'));
  
  const tasks = new Listr([
    {
      title: '任务 1: 下载依赖',
      task: () => {
        return new Promise(resolve => setTimeout(resolve, 2000));
      }
    },
    {
      title: '任务 2: 构建项目',
      task: () => {
        return new Promise(resolve => setTimeout(resolve, 3000));
      }
    },
    {
      title: '任务 3: 部署应用',
      task: () => {
        return new Promise((resolve, reject) => {
          setTimeout(() => {
            resolve();
          }, 2500);
        });
      }
    }
  ]);
  
  tasks.run().then(() => {
    console.log('');
    console.log(chalk.green('所有任务执行完成！'));
  }).catch(err => {
    console.error(chalk.red('任务执行失败:', err));
  });
}

// 启动进度显示
singleProgress();

3. 配置 package.json

{
  "name": "progress-cli",
  "version": "1.0.0",
  "description": "进度显示 CLI 工具",
  "bin": {
    "progress-cli": "bin/progress-cli.js"
  },
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "cli",
    "progress"
  ],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "chalk": "^5.0.0",
    "listr": "^0.14.3",
    "ora": "^6.0.0"
  }
}

4. 测试进度显示 CLI 工具

# 链接到全局
npm link

# 运行进度显示 CLI 工具
progress-cli

CLI 工具开发最佳实践

1. 命令设计

• 命令结构：

  • 保持命令简洁明了
  • 使用一致的命名约定
  • 对于多命令工具，合理组织子命令

• 参数设计：

  • 使用有意义的参数名称
  • 提供默认值
  • 支持短选项和长选项

• 帮助信息：

  • 提供详细的帮助文档
  • 为每个命令和选项添加描述
  • 示例用法

2. 用户体验

• 反馈机制：

  • 提供清晰的成功和错误消息
  • 使用颜色和样式增强可读性
  • 显示进度信息

• 错误处理：

  • 优雅处理错误
  • 提供有用的错误消息
  • 使用适当的退出码

• 交互式提示：

  • 对于复杂操作，提供交互式提示
  • 允许用户确认危险操作
  • 提供合理的默认值

3. 代码质量

• 模块化：

  • 将代码分解为模块
  • 使用清晰的文件结构
  • 遵循代码风格指南

• 测试：

  • 编写单元测试
  • 测试命令行参数解析
  • 测试错误处理

• 文档：

  • 编写 README 文件
  • 提供命令参考文档
  • 示例用法

4. 打包和发布

• package.json 配置：

  • 正确设置 bin 字段
  • 添加适当的依赖
  • 配置 scripts

• 可执行文件：

  • 添加 shebang 行 (#!/usr/bin/env node)
  • 设置文件权限为可执行
  • 考虑使用 pkg 或 nexe 打包为可执行文件

• 发布到 npm：

  • 选择合适的包名
  • 编写清晰的描述
  • 添加关键词

5. 性能和可靠性

• 性能优化：

  • 避免不必要的文件系统操作
  • 优化命令行参数解析
  • 减少依赖

• 可靠性：

  • 处理边缘情况
  • 验证用户输入
  • 提供回滚机制

• 跨平台兼容性：

  • 避免使用平台特定的命令
  • 处理路径分隔符差异
  • 测试不同操作系统

常见问题与解决方案

问题 1：命令行参数解析错误

症状：

• 命令行参数无法正确解析
• 选项参数不生效
• 子命令无法识别

解决方案：

• 检查 commander 版本，确保使用正确的 API
• 确保命令和选项的顺序正确
• 使用 program.parse(process.argv) 解析参数
• 检查子命令的注册方式

问题 2：交互式命令行不响应

症状：

• inquirer 提示不显示
• 用户输入无响应
• 交互式菜单无法选择

解决方案：

• 确保使用正确版本的 inquirer
• 检查问题配置是否正确
• 确保没有其他进程占用标准输入
• 测试不同终端环境

问题 3：文件路径处理错误

症状：

• 相对路径无法正确解析
• 跨平台路径分隔符问题
• 文件权限错误

解决方案：

• 使用 path.resolve() 解析绝对路径
• 使用 path.join() 连接路径
• 处理文件权限错误
• 测试不同操作系统的路径处理

问题 4：子进程执行失败

症状：

• 子进程执行无响应
• 子进程输出无法捕获
• 子进程错误处理失败

解决方案：

• 使用 execa 替代内置的 child_process
• 正确处理子进程的 stdout 和 stderr
• 设置合理的超时时间
• 处理子进程的错误

问题 5：CLI 工具安装后无法运行

症状：

• 命令未找到错误
• 权限被拒绝错误
• 模块未找到错误

解决方案：

• 确保 package.json 中的 bin 字段配置正确
• 确保可执行文件有正确的 shebang 行
• 确保文件权限为可执行
• 检查依赖是否正确安装

CLI 工具开发工具比较

总结

CLI 工具开发是 Node.js 生态系统中的重要组成部分，它可以帮助开发者自动化任务、提高效率、构建实用工具。通过本文的学习，你应该：

1. 理解 CLI 工具的核心概念和优势
2. 掌握使用 commander、inquirer 等库构建 CLI 工具
3. 学会实现交互式命令行、进度显示等高级功能
4. 了解 CLI 工具开发的最佳实践和常见问题解决方案
5. 能够构建功能完整、用户友好的 CLI 工具

CLI 工具开发不仅是一种技术，更是一种思维方式。通过命令行工具，你可以将复杂的任务简化为简单的命令，提高工作效率，为用户提供更好的工具体验。随着 Node.js 生态系统的不断发展，CLI 工具开发也变得越来越简单和强大。

记住，一个好的 CLI 工具应该是简洁、高效、用户友好的。在开发过程中，始终关注用户体验，提供清晰的反馈和错误处理，这样才能构建出优秀的 CLI 工具。