全栈攻城狮

Appearance

前端 CLI 工具开发 ​

概述 ​

命令行界面（CLI）工具是前端工程化体系中不可或缺的一环。从项目脚手架生成、代码检查、构建打包到自动化部署，CLI 工具贯穿了整个开发流程。本文将系统性地介绍使用 Node.js 开发前端 CLI 工具所需的核心知识，涵盖命令解析库、模板引擎、自动化脚本、工程化配置及发布流程。

Commander.js ​

Commander.js 是 Node.js 生态中最流行的命令行框架之一，以其简洁的 API 和完善的功能深受开发者喜爱。

定义命令 ​

Commander 的核心是 Command 对象，通过它可以定义程序的名称、版本号和描述信息：

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

program
  .name('my-cli')
  .description('一个功能强大的前端 CLI 工具')
  .version('1.0.0');

定义选项 ​

Commander 支持多种选项类型，包括布尔选项、带值的选项和可选值选项：

javascript
program
  .option('-d, --debug', '开启调试模式')
  .option('-c, --config <path>', '配置文件路径')
  .option('-o, --output [dir]', '输出目录')
  .option('--no-cache', '禁用缓存');

选项可以通过 short 和 long 两种形式定义，<required> 尖括号表示必填参数，[optional] 方括号表示可选参数。

定义参数 ​

命令参数通过 .arguments() 或 .argument() 方法定义：

javascript
program
  .arguments('<project-name> [template]')
  .description('创建一个新项目')
  .action((projectName, template) => {
    console.log(`创建项目: ${projectName}`);
    if (template) {
      console.log(`使用模板: ${template}`);
    }
  });

子命令 ​

对于复杂的 CLI 工具，子命令是组织功能的最佳方式。Commander 支持两种子命令模式：

独立可执行文件模式：

javascript
const program = new Command();

program
  .command('build', '构建项目')
  .command('deploy', '部署项目')
  .command('serve', '启动开发服务器');

内联子命令模式：

javascript
program
  .command('init <name>')
  .description('初始化项目')
  .option('-t, --type <type>', '项目类型')
  .action((name, options) => {
    // 初始化逻辑
  });

program
  .command('generate <type>')
  .description('生成代码片段')
  .alias('g')
  .addHelpText('after', '示例: my-cli generate component Button')
  .action((type) => {
    // 生成逻辑
  });

自定义帮助信息 ​

Commander 允许高度定制帮助信息的展示方式：

javascript
program
  .helpOption('-h, --help', '查看帮助信息')
  .addHelpText('beforeAll', '欢迎使用 MyCLI！\n')
  .addHelpText('afterAll', '\n更多信息请访问 https://example.com')
  .addHelpText('before', '用法说明:')
  .addHelpText('after', '注意：某些选项需要 Node.js 16+');

钩子函数 ​

Commander 提供了生命周期钩子，允许在命令执行的不同阶段插入自定义逻辑：

javascript
program
  .hook('preAction', (thisCommand, actionCommand) => {
    console.log('命令执行前触发');
    // 可以在此处进行权限检查、环境准备等
  })
  .hook('postAction', (thisCommand, actionCommand) => {
    console.log('命令执行后触发');
    // 可以在此处进行清理工作
  });

支持的生命周期钩子包括：preAction、postAction、preSubcommand 和 postSubcommand。

自动补全 ​

Commander 内置了对 shell 自动补全的支持：

javascript
// 生成补全脚本
program.addCompletionCommand('completion');

用户可以通过 source <(my-cli completion) 命令启用自动补全功能，Commander 会为 bash、zsh 和 fish 等主流 shell 生成对应的补全脚本。

yargs ​

yargs 是另一个广泛使用的命令行解析库，以其强大的解析能力和灵活的配置选项著称。

命令构建 ​

yargs 采用链式调用的方式构建命令：

javascript
const yargs = require('yargs');

yargs
  .command('create <name>', '创建一个新项目', (yargs) => {
    yargs
      .positional('name', {
        describe: '项目名称',
        type: 'string'
      })
      .option('template', {
        alias: 't',
        describe: '模板类型',
        type: 'string',
        choices: ['vue', 'react', 'svelte']
      });
  }, (argv) => {
    console.log(`创建项目: ${argv.name}`);
    console.log(`使用模板: ${argv.template || 'default'}`);
  })
  .parse();

选项解析 ​

yargs 的选项解析功能非常强大，支持类型检查、默认值和自定义验证：

javascript
const argv = yargs
  .option('port', {
    alias: 'p',
    describe: '端口号',
    type: 'number',
    default: 3000
  })
  .option('host', {
    describe: '主机地址',
    type: 'string',
    default: 'localhost'
  })
  .option('verbose', {
    alias: 'v',
    describe: '详细输出',
    type: 'boolean',
    count: true  // 支持 -vvv 累加
  })
  .check((argv, options) => {
    if (argv.port < 0 || argv.port > 65535) {
      throw new Error('端口号必须在 0-65535 之间');
    }
    return true;
  })
  .parse();

位置参数 ​

位置参数是命令行的核心组成部分，yargs 提供了完善的声明方式：

javascript
yargs
  .command('deploy [environment]', '部署到指定环境', (yargs) => {
    yargs
      .positional('environment', {
        describe: '目标环境',
        type: 'string',
        choices: ['development', 'staging', 'production'],
        default: 'development'
      });
  });

中间件 ​

yargs 的中间件机制允许在命令执行前执行公共逻辑：

javascript
yargs
  .middleware((argv) => {
    // 公共配置加载
    if (argv.config) {
      const config = require(path.resolve(argv.config));
      Object.assign(argv, config);
    }
  })
  .middleware(async (argv) => {
    // 异步中间件
    argv.user = await getUserInfo();
  })
  .command('serve', '启动服务器', () => {}, (argv) => {
    console.log(`用户: ${argv.user.name}`);
  });

严格模式 ​

yargs 的严格模式可以帮助开发者捕获配置错误：

javascript
yargs
  .strict()        // 禁止未知选项
  .strictCommands() // 禁止未知命令
  .strictOptions() // 禁用选项的模糊匹配
  .parse();

启用严格模式后，yargs 会在遇到未定义的选项或命令时自动报错，提升工具的可靠性。

Commander 与 yargs 对比 ​

特性Commander.jsyargs
学习曲线平缓，API 直观中等，配置丰富
子命令支持原生支持，两种模式通过 command() 实现
自动补全内置支持需要额外配置
选项类型支持多种类型类型更丰富
中间件通过钩子实现原生支持
帮助信息高度可定制自动生成，定制有限
参数验证自定义验证内置 check 方法
生态系统广泛使用插件丰富
适用场景中小型 CLI 工具复杂命令行应用

模板生成 ​

模板生成是脚手架工具的核心功能，通过模板引擎将用户输入与预定义模板结合，生成最终的项目文件。

EJS 模板引擎 ​

EJS 是最简单直接的模板引擎，使用 JavaScript 语法进行模板渲染：

javascript
const ejs = require('ejs');

const template = `
欢迎使用 <%= name %> 脚手架！
版本: <%= version %>
功能模块:
<% modules.forEach(function(mod) { %>
  - <%= mod %>
<% }); %>
`;

const result = ejs.render(template, {
  name: 'MyApp',
  version: '1.0.0',
  modules: ['Router', 'Store', 'Auth']
});

EJS 支持 include 指令实现模板复用：

javascript
// components.ejs
<% include header %>
<main>
  <h1><%= pageTitle %></h1>
</main>
<% include footer %>

Handlebars 模板引擎 ​

Handlebars 以其逻辑无关（logic-less）的模板设计理念著称，强调模板与业务逻辑的分离：

handlebars
// package.hbs
{
  "name": "&#123;&#123;projectName&#125;&#125;",
  "version": "&#123;&#123;version&#125;&#125;",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    &#123;&#123;#each dependencies&#125;&#125;
    "&#123;&#123;@key&#125;&#125;": "&#123;&#123;this&#125;&#125;"&#123;&#123;#unless @last&#125;&#125;,&#123;&#125;/unless&#125;&#125;
    &#123;&#125;/each&#125;&#125;
  }
}
javascript
const Handlebars = require('handlebars');

const source = fs.readFileSync('package.hbs', 'utf-8');
const template = Handlebars.compile(source);
const output = template({
  projectName: 'my-app',
  version: '1.0.0',
  dependencies: { vue: '^3.4.0', vuex: '^4.0.0' }
});

Handlebars 还支持自定义 helper 以扩展模板功能：

javascript
Handlebars.registerHelper('eq', (a, b) => a === b);
Handlebars.registerHelper('upper', (str) => str.toUpperCase());

Nunjucks 模板引擎 ​

Nunjucks 是 Mozilla 开发的模板引擎，兼具 Jinja2 的强大能力和 JavaScript 的灵活性：

nunjucks
// config.njk
{% if framework === 'vue' %}
import { createApp } from 'vue'
{% elif framework === 'react' %}
import React from 'react'
{% endif %}

const appConfig = {
  title: "&#123;&#123; appName | title &#125;&#125;",
  features: [
    {% for feature in features %}
    { name: "&#123;&#123; feature &#125;&#125;", enabled: true }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
};
javascript
const nunjucks = require('nunjucks');

nunjucks.configure('templates', { autoescape: true });
const result = nunjucks.render('config.njk', {
  framework: 'vue',
  appName: 'my awesome app',
  features: ['router', 'pinia', 'i18n']
});

模板变量与条件渲染 ​

三种模板引擎的变量和条件语法对比：

操作EJSHandlebarsNunjucks
输出变量<%= var %>{{var}}{{var}}
条件判断<% if (cond) { %>{{#if cond}}{% if cond %}
循环<% items.forEach(i => { %>{{#each items}}{% for i in items %}
过滤器/管道无原生支持通过 helper`{{ var
模板继承include无extends/block
宏无无macro

选择建议：

  • EJS：适合需要 JavaScript 全能力的场景，学习成本最低
  • Handlebars：适合强调模板与逻辑分离的大型团队
  • Nunjucks：适合需要复杂模板继承和宏的高级场景

文件生成策略 ​

文件生成涉及以下几个核心步骤：

javascript
async function generateFiles(templateDir, outputDir, context) {
  const files = await glob('**/*', { cwd: templateDir, dot: true });

  for (const file of files) {
    const sourcePath = path.join(templateDir, file);
    const relativePath = file.replace(/\.(ejs|hbs|njk)$/, '');
    const outputPath = path.join(outputDir, renderPath(relativePath, context));

    // 确保输出目录存在
    await fs.mkdir(path.dirname(outputPath), { recursive: true });

    // 渲染模板文件
    if (isTemplateFile(file)) {
      const content = await renderTemplate(sourcePath, context);
      await fs.writeFile(outputPath, content, 'utf-8');
    } else {
      // 二进制文件直接复制
      await fs.copyFile(sourcePath, outputPath);
    }
  }
}

文件覆盖策略 ​

当目标文件已存在时，需要合理的覆盖策略：

javascript
async function handleFileConflict(targetPath, newContent) {
  if (!await fs.pathExists(targetPath)) {
    return 'create';
  }

  const existingContent = await fs.readFile(targetPath, 'utf-8');
  if (existingContent === newContent) {
    return 'identical';
  }

  // 交互式询问
  const { action } = await inquirer.prompt([
    {
      type: 'list',
      name: 'action',
      message: `${targetPath} 已存在，如何处理？`,
      choices: [
        { name: '覆盖', value: 'overwrite' },
        { name: '跳过', value: 'skip' },
        { name: '全部覆盖', value: 'overwriteAll' },
        { name: '全部跳过', value: 'skipAll' },
        { name: '显示差异', value: 'diff' }
      ]
    }
  ]);

  return action;
}

自动化脚本 ​

自动化脚本是 CLI 工具提升效率的关键，涵盖了文件操作、交互提示、Git 操作等多个方面。

文件操作 ​

Node.js 的 fs 模块提供了完整的文件操作能力：

javascript
const fs = require('fs-extra');
const path = require('path');

// 递归创建目录
await fs.ensureDir('./src/components');

// 写入文件
await fs.writeFile('./src/app.js', '// file content');

// 复制模板目录
await fs.copy('./templates/project', './my-project');

// 读取并解析 JSON
const pkg = await fs.readJson('./package.json');

// 修改 JSON 并保存
pkg.scripts.dev = 'vite --port 3000';
await fs.writeJson('./package.json', pkg, { spaces: 2 });

交互式提示 ​

使用 inquirer 库实现丰富的用户交互：

javascript
const inquirer = require('inquirer');

const answers = await inquirer.prompt([
  {
    type: 'input',
    name: 'projectName',
    message: '请输入项目名称：',
    default: 'my-app',
    validate: (input) => {
      if (!/^[a-z][a-z0-9-]*$/.test(input)) {
        return '项目名称必须是小写字母开头，只能包含小写字母、数字和连字符';
      }
      return true;
    }
  },
  {
    type: 'list',
    name: 'packageManager',
    message: '请选择包管理器：',
    choices: ['npm', 'pnpm', 'yarn']
  },
  {
    type: 'confirm',
    name: 'installNow',
    message: '是否立即安装依赖？',
    default: true
  }
]);

Git 操作 ​

通过 shell 命令或专用的 Git 库可以实现在 CLI 中自动执行 Git 操作：

javascript
const { execa } = require('execa');

async function initGitRepo(projectDir) {
  await execa('git', ['init'], { cwd: projectDir });
  await execa('git', ['add', '.'], { cwd: projectDir });
  await execa('git', ['commit', '-m', 'chore: 初始化项目'], { cwd: projectDir });
}

async function createGitBranch(branchName) {
  await execa('git', ['checkout', '-b', branchName]);
}

依赖安装 ​

根据用户选择的包管理器执行依赖安装：

javascript
async function installDependencies(projectDir, packageManager) {
  const spinner = ora('正在安装依赖...').start();

  try {
    const installCmd = {
      npm: 'install',
      pnpm: 'install',
      yarn: undefined  // yarn install 是默认行为
    };

    await execa(packageManager, installCmd[packageManager] || [], {
      cwd: projectDir,
      stdio: 'pipe'
    });

    spinner.succeed('依赖安装完成');
  } catch (error) {
    spinner.fail('依赖安装失败');
    throw error;
  }
}

自动提交与发布脚本 ​

结合语义化版本控制，可以实现完整的发布流水线：

javascript
async function release(versionType = 'patch') {
  // 1. 运行测试
  console.log('正在运行测试...');
  await execa('npm', ['test']);

  // 2. 构建
  console.log('正在构建...');
  await execa('npm', ['run', 'build']);

  // 3. 更新版本号
  await execa('npm', ['version', versionType]);

  // 4. 生成 changelog
  await execa('npx', ['conventional-changelog', '-p', 'angular', '-i', 'CHANGELOG.md', '-s']);

  // 5. 提交 changelog
  await execa('git', ['add', 'CHANGELOG.md']);
  await execa('git', ['commit', '-m', `docs: 更新 ${versionType} 版本 changelog`]);

  // 6. 推送到远程
  await execa('git', ['push', '--follow-tags']);

  // 7. 发布到 npm
  await execa('npm', ['publish']);

  console.log(`版本 ${versionType} 发布成功！`);
}

CLI 工程化 ​

将 CLI 工具工程化涉及项目结构设计、配置文件编写和开发调试流程。

项目结构 ​

一个典型的 CLI 工具项目结构如下：

my-cli/
├── bin/
│   └── cli.js          # 入口文件
├── src/
│   ├── commands/        # 命令实现
│   │   ├── init.js
│   │   ├── build.js
│   │   └── deploy.js
│   ├── utils/           # 工具函数
│   │   ├── logger.js
│   │   └── file.js
│   └── templates/       # 模板文件
│       ├── package.ejs
│       └── readme.ejs
├── package.json
└── README.md

bin 配置 ​

在 package.json 中通过 bin 字段指定 CLI 工具的入口：

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

可以为 CLI 工具设置多个命令名称，指向同一个入口文件。

Shebang ​

入口文件的第一行必须是 shebang，指明使用 Node.js 来执行此脚本：

javascript
#!/usr/bin/env node

'use strict';

const { Command } = require('commander');
// ... CLI 实现

#!/usr/bin/env node 会自动查找系统中的 Node.js 可执行文件，保证跨平台兼容性。

在开发过程中，使用 npm link 将 CLI 工具链接到全局，方便本地测试：

bash
# 在项目目录中创建全局符号链接
npm link

# 验证链接是否成功
my-cli --version

# 解除链接
npm unlink my-cli

# 或者在项目根目录执行
npm uninstall -g my-cli

对于更复杂的调试场景，可以使用 node inspect 或 VS Code 的调试配置：

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug CLI",
      "program": "${workspaceFolder}/bin/cli.js",
      "args": ["init", "my-app", "--template", "vue"]
    }
  ]
}

版本管理 ​

使用 npm version 命令进行版本管理，遵循语义化版本规范：

bash
# 补丁版本（1.0.0 -> 1.0.1）
npm version patch

# 次要版本（1.0.0 -> 1.1.0）
npm version minor

# 主要版本（1.0.0 -> 2.0.0）
npm version major

# 预发布版本（1.0.0 -> 1.0.0-beta.0）
npm version prerelease --preid beta

每次执行 npm version 都会自动创建一个 Git tag，便于后续追踪版本历史。

用户交互 ​

优秀的用户体验是 CLI 工具成功的关键，本节介绍提升交互体验的各类工具。

inquirer 交互提示 ​

inquirer 提供了丰富的交互式提示类型：

javascript
const inquirer = require('inquirer');

const answers = await inquirer.prompt([
  {
    type: 'input',       // 文本输入
    name: 'username',
    message: '用户名：'
  },
  {
    type: 'password',    // 密码输入（隐藏）
    name: 'password',
    message: '密码：'
  },
  {
    type: 'confirm',     // 确认
    name: 'continue',
    message: '是否继续？',
    default: true
  },
  {
    type: 'list',        // 单选列表
    name: 'framework',
    message: '选择框架：',
    choices: ['Vue', 'React', 'Svelte', 'Solid']
  },
  {
    type: 'checkbox',    // 多选
    name: 'features',
    message: '选择功能：',
    choices: [
      { name: 'TypeScript', checked: true },
      { name: 'ESLint', checked: true },
      { name: 'Prettier' },
      { name: 'Unit Testing' }
    ]
  },
  {
    type: 'rawlist',     // 编号列表
    name: 'theme',
    message: '选择主题：',
    choices: ['Light', 'Dark', 'System']
  },
  {
    type: 'expand',      // 展开式选择
    name: 'action',
    message: '冲突处理方式：',
    choices: [
      { key: 'o', name: '覆盖', value: 'overwrite' },
      { key: 's', name: '跳过', value: 'skip' },
      { key: 'd', name: '显示差异', value: 'diff' }
    ]
  }
]);

Progress Bar 进度条 ​

使用 cli-progress 库展示任务进度：

javascript
const cliProgress = require('cli-progress');

const bar = new cliProgress.SingleBar({
  format: '进度 |{bar}| {percentage}% | {value}/{total} 文件',
  barCompleteChar: '█',
  barIncompleteChar: '░',
  hideCursor: true
});

const files = await getFiles();
bar.start(files.length, 0);

for (const file of files) {
  await processFile(file);
  bar.increment();
}

bar.stop();

ora Spinner 加载动画 ​

使用 ora 在耗时操作中展示加载状态：

javascript
const ora = require('ora');

const spinner = ora('正在下载模板...').start();

try {
  await downloadTemplate();
  spinner.succeed('模板下载完成');
} catch (error) {
  spinner.fail('模板下载失败');
  spinner.info('请检查网络连接后重试');
}

ora 支持多种 spinner 样式，可以通过 ora({ spinner: 'dots' }) 进行配置。

Chalk 颜色输出 ​

使用 chalk 为终端输出添加色彩，提升可读性：

javascript
const chalk = require('chalk');

// 基本颜色
console.log(chalk.red('错误信息'));
console.log(chalk.green('成功信息'));
console.log(chalk.blue('提示信息'));
console.log(chalk.yellow('警告信息'));

// 样式组合
console.log(chalk.bold.underline('加粗下划线'));
console.log(chalk.bgRed.white('红色背景白色文字'));

// 条件着色
const level = 'warn';
const colorMap = {
  info: chalk.blue,
  warn: chalk.yellow,
  error: chalk.red
};
console.log(colorMap[level](`[${level.toUpperCase()}] 信息内容`));

CLI 发布流程 ​

npm publish 发布 ​

将 CLI 工具发布到 npm 仓库的基本流程：

bash
# 确保已登录
npm login

# 检查是否包含不必要的文件
npm pack --dry-run

# 发布
npm publish

# 发布 beta 版本
npm publish --tag beta

# 发布到 scope
npm publish --access public

建议在发布前通过 .npmignore 文件或 package.json 的 files 字段控制发布内容：

json
{
  "files": [
    "bin/",
    "src/",
    "templates/",
    "README.md",
    "LICENSE"
  ]
}

语义化版本 ​

遵循语义化版本规范（SemVer）管理版本号：

  • major：不兼容的 API 修改（1.0.0 -> 2.0.0）
  • minor：向下兼容的功能新增（1.0.0 -> 1.1.0）
  • patch：向下兼容的问题修复（1.0.0 -> 1.0.1）
  • pre-release：预发布版本（1.0.0-alpha.0, 1.0.0-beta.1）

版本号的增长应严格遵循规范，避免随意跳版本。

更新通知 ​

在 CLI 工具中集成版本更新检查，提醒用户升级：

javascript
const updateNotifier = require('update-notifier');
const pkg = require('./package.json');

const notifier = updateNotifier({
  pkg,
  updateCheckInterval: 1000 * 60 * 60 * 24  // 24 小时检查一次
});

if (notifier.update) {
  notifier.notify({
    message: `新版本可用：${chalk.cyan(notifier.update.current)} -> ${chalk.green(notifier.update.latest)}\n` +
      `建议更新：${chalk.yellow('npm update -g ' + pkg.name)}`
  });
}

自动更新 ​

实现自动更新功能，让用户一键升级：

javascript
const updateNotifier = require('update-notifier');
const { execa } = require('execa');

async function checkAndUpdate() {
  const notifier = updateNotifier({ pkg: require('./package.json') });

  if (notifier.update) {
    const { shouldUpdate } = await inquirer.prompt([
      {
        type: 'confirm',
        name: 'shouldUpdate',
        message: `新版本 ${notifier.update.latest} 可用，是否更新？`,
        default: true
      }
    ]);

    if (shouldUpdate) {
      const spinner = ora('正在更新...').start();
      try {
        await execa('npm', ['install', '-g', pkg.name]);
        spinner.succeed('更新成功，请重新运行命令');
        process.exit(0);
      } catch (error) {
        spinner.fail('更新失败，请手动执行 npm install -g my-cli');
      }
    }
  }
}

配置持久化 ​

使用 conf 或 cosmiconfig 库持久化用户配置：

javascript
const Conf = require('conf');

const config = new Conf({
  projectName: 'my-cli',
  defaults: {
    theme: 'dark',
    editor: 'code',
    registry: 'https://registry.npmjs.org/'
  }
});

// 读取配置
const theme = config.get('theme');

// 写入配置
config.set('editor', 'vim');

// 重置配置
config.reset();

// 配置文件默认存储在
// macOS: ~/Library/Preferences/my-cli-nodejs.json
// Windows: %APPDATA%/my-cli-nodejs/Config.json
// Linux: ~/.config/my-cli-nodejs.json

总结 ​

本文全面介绍了前端 CLI 工具开发的核心技术栈，从命令解析（Commander.js 和 yargs）到模板生成（EJS、Handlebars、Nunjucks），从自动化脚本到工程化配置，再到用户交互和发布流程。这些知识构成了一个完整的 CLI 工具开发知识体系，能够帮助开发者构建出高质量、用户友好的命令行工具。

在实际开发中，合理选择技术组合至关重要。对于简单工具，Commander.js 搭配 EJS 即可满足需求；对于大型 CLI 项目，可以考虑 yargs 配合 Nunjucks，并加入完善的错误处理和用户反馈机制。