从零开始制作 CLI 工具:快速创建项目脚手架

在现代前端开发中,项目初始化是一个高频且重复的操作。脚手架工具通过自动化项目结构的创建和基础配置的设定,显著提升开发效率。本教程将指导你从零开发一个 CLI(Command Line Interface)脚手架工具,它能够:

  • 🚀 一键生成标准化的项目结构
  • ⚙️ 根据用户选择动态配置项目
  • 📁 自动安装依赖项
  • 🔄 替换模板变量(如项目名称、作者等)

常见的脚手架工具如 create-react-app 或 vue-cli 都采用了类似原理。我们将创建一个简化版但功能完整的工具:create-my-app。

目录#

  1. 引言:为什么需要脚手架工具
  2. 核心概念解析
  3. 开发环境准备
  4. 构建 CLI 工具基础框架
  5. 实现脚手架核心功能
  6. 高级功能实现
  7. 最佳实践与常见陷阱
  8. 发布到 npm 仓库
  9. 示例用法
  10. 结语
  11. 参考资源

2. 核心概念解析#

关键组件#

组件作用实现技术
命令行解析处理用户输入的命令和参数commander.js
用户交互收集用户配置选择inquirer.js
模板渲染动态生成项目文件ejs 模板引擎
文件操作复制/创建文件fs-extra
依赖管理自动安装依赖execa(调用 npm)

工作流程#

graph TD
    A[用户执行 CLI 命令] --> B[解析命令行参数]
    B --> C[交互式收集配置]
    C --> D[复制模板文件]
    D --> E[动态渲染模板]
    E --> F[安装依赖]
    F --> G[完成提示]

3. 开发环境准备#

确保系统已安装:

  • Node.js (≥ v16)
  • npm (≥ v8)

创建项目目录:

mkdir create-my-app && cd create-my-app
npm init -y

安装核心依赖:

npm install commander inquirer ejs fs-extra execa chalk -S

配置 package.json 入口:

{
  "bin": {
    "create-my-app": "bin/index.js"
  },
  "type": "module"  // 使用 ES Modules
}

4. 构建 CLI 工具基础框架#

文件结构#

create-my-app/
├── bin/
│   └── index.js      # CLI 入口
├── templates/        # 存放项目模板
├── utils/            # 工具函数
│   └── render.js
└── package.json

入口文件:bin/index.js#

#!/usr/bin/env node
 
import { Command } from 'commander';
import inquirer from 'inquirer';
import { createProject } from '../lib/core.js';
 
const program = new Command();
 
program
  .name('create-my-app')
  .description('快速生成项目脚手架')
  .version('1.0.0');
 
program
  .command('init <project-name>')
  .description('初始化新项目')
  .action(async (name) => {
    // 1. 收集用户配置
    const answers = await promptUser();
    
    // 2. 创建项目
    await createProject(name, answers);
  });
 
program.parse(process.argv);
 
async function promptUser() {
  return inquirer.prompt([
    {
      type: 'list',
      name: 'framework',
      message: '请选择框架:',
      choices: ['React', 'Vue', 'NodeJS']
    },
    {
      type: 'checkbox',
      name: 'features',
      message: '选择附加功能:',
      choices: ['ESLint', 'Prettier', 'Unit Test']
    }
  ]);
}

5. 实现脚手架核心功能#

文件操作与模板渲染:lib/core.js#

import fs from 'fs-extra';
import path from 'path';
import { renderDir } from './utils/render.js';
import { installDependencies } from './utils/install.js';
 
export async function createProject(projectName, options) {
  const projectPath = path.resolve(process.cwd(), projectName);
  
  // 创建项目目录
  if (fs.existsSync(projectPath)) {
    throw new Error(`目录 ${projectName} 已存在!`);
  }
  fs.mkdirSync(projectPath);
  
  // 渲染模板(含变量替换)
  const templatePath = path.resolve(
    __dirname, 
    `../templates/${options.framework.toLowerCase()}`
  );
  
  await renderDir(templatePath, projectPath, {
    projectName,
    features: options.features.join(', ')
  });
  
  // 自动安装依赖
  if (options.autoInstall) {
    await installDependencies(projectPath);
  }
  
  console.log(`✅ 项目创建成功!执行以下命令启动:
cd ${projectName}
npm run dev`);
}

模板渲染工具:utils/render.js#

import fs from 'fs-extra';
import path from 'path';
import ejs from 'ejs';
 
export async function renderDir(source, target, data) {
  // 确保目标目录存在
  await fs.ensureDir(target);
  
  // 遍历模板目录
  const files = await fs.readdir(source);
  
  for (const file of files) {
    const srcPath = path.join(source, file);
    const tarPath = path.join(target, file);
    const stats = await fs.stat(srcPath);
    
    if (stats.isDirectory()) {
      await renderDir(srcPath, tarPath, data);
    } else if (file.endsWith('.ejs')) {
      // 渲染EJS模板文件
      const content = await ejs.renderFile(srcPath, data);
      await fs.writeFile(tarPath.replace('.ejs', ''), content);
    } else {
      // 直接复制非模板文件
      await fs.copy(srcPath, tarPath);
    }
  }
}

依赖安装工具:utils/install.js#

import { execa } from 'execa';
import chalk from 'chalk';
 
export async function installDependencies(projectPath) {
  console.log(chalk.blue('📦 安装依赖中...'));
  
  try {
    await execa('npm', ['install'], {
      cwd: projectPath,
      stdio: 'inherit'  // 显示安装进度
    });
  } catch (error) {
    console.log(chalk.red('⚠️ 依赖安装失败,请手动安装'));
  }
}

6. 高级功能实现#

钩子系统(Hooks)#

在项目创建流程中插入自定义操作:

// lib/core.js
async function runHook(hookName, context) {
  const hookPath = path.join(__dirname, `../hooks/${hookName}.js`);
  
  if (fs.existsSync(hookPath)) {
    const { default: hook } = await import(hookPath);
    await hook(context);
  }
}
 
// 在 createProject 中添加:
await runHook('pre-create', { projectName, options });
// ...创建流程...
await runHook('post-create', { projectPath });

本地调试模式#

// 在命令中添加调试选项
program.command('init <project-name>')
  .option('--debug', '启用调试模式')
  .action(async (name, cmdObj) => {
    if (cmdObj.debug) {
      // 显示详细日志
      process.env.DEBUG = 'true';
    }
  });

Git 仓库初始化#

import { execa } from 'execa';
 
export async function initGitRepo(projectPath) {
  try {
    await execa('git', ['init'], { cwd: projectPath });
    await execa('git', ['add', '.'], { cwd: projectPath });
    await execa('git', ['commit', '-m', '初始提交'], { cwd: projectPath });
  } catch (e) {
    console.log(chalk.yellow('⚠️ Git 初始化失败'));
  }
}

7. 最佳实践与常见陷阱#

最佳实践#

  1. 模板设计原则

    • 保持模板最小化,只包含必要结构
    • 使用.ejs扩展名标识需渲染的文件
    • 敏感信息用占位符代替(如<%= API_KEY %>)
  2. 错误处理

    process.on('unhandledRejection', (err) => {
      console.error(chalk.red(`[致命错误] ${err.message}`));
      process.exit(1);
    });
  3. 性能优化

    • 使用fs.copy代替递归复制
    • 并行化无依赖的操作

常见陷阱#

问题解决方案
权限不足在package.json中设置"preferGlobal": true
跨平台问题使用path.join()代替字符串拼接路径
长耗时操作添加进度指示器(如ora库)
用户中断监听SIGINT事件并清理临时文件

8. 发布到 npm 仓库#

  1. 登录 npm 账号

    npm login
  2. 添加文件白名单(防止发布模板文件)

    // package.json
    "files": ["bin", "lib", "utils"]
  3. 发布包

    npm publish --access public
  4. 用户全局安装

    npm install -g create-my-app

9. 示例用法#

基本使用#

create-my-app init my-project

启用自动安装#

create-my-app init my-project --install

调试模式#

create-my-app init my-project --debug

流程演示#

? 请选择框架: (Use arrow keys)
> React 
  Vue 
  NodeJS
 
? 选择附加功能: (Press <space> to select)
◯ ESLint
◯ Prettier
◉ Unit Test
 
[开始创建项目] 复制模板中...
[渲染模板] 替换变量中...
[依赖安装] npm install...
 
✅ 项目创建成功!执行以下命令启动:
cd my-project
npm run dev

10. 结语#

通过本教程,你已经学会了如何:

  1. 构建专业的 CLI 工具架构
  2. 实现动态模板渲染功能
  3. 增加自动化依赖安装
  4. 应用错误处理和用户交互最佳实践

完整的示例代码可在 GitHub 获取:https://github.com/example/create-my-app(示例链接)

进阶建议:

  • 增加模板远程更新功能
  • 支持多源模板选择(GitHub/GitLab)
  • 集成 CI/CD 配置生成

欢迎在评论区分享你创建的脚手架工具!🚀

11. 参考资源#

  1. Commander.js 官方文档
  2. Inquirer.js 交互示例
  3. Node.js 文件系统最佳实践
  4. Creating a Professional CLI Tool
  5. npm 发布指南

版权声明:自由转载-非商用-非衍生-保持署名(创意共享 3.0 许可证)