从零构建现代前端脚手架：不只是 `create-react-app`

在当今的前端开发中，脚手架工具已经成为项目启动的标配。从 create-react-app 到 Vite，从 Vue CLI 到 Next.js 的初始化命令，这些工具极大地提升了开发效率。但你是否曾想过，这些脚手架背后是如何工作的？当现有脚手架无法满足你的团队特定需求时，如何构建一个定制化的脚手架工具？

本文将带你深入脚手架的实现原理，从零开始构建一个功能完整的现代前端脚手架工具，涵盖模板管理、动态配置、插件系统等核心功能。

为什么需要自定义脚手架？

虽然市面上有众多优秀的通用脚手架，但在企业级开发中，我们常常面临以下痛点：

1. 技术栈定制：公司内部有特定的技术栈组合（如特定的UI库、状态管理、工具链）
2. 规范统一：需要强制统一的代码规范、目录结构、Git提交规范等
3. 效率优化：集成内部工具链（如微前端框架、私有npm包、CI/CD配置）
4. 知识沉淀：将最佳实践固化到模板中，降低新人上手成本

脚手架核心架构设计

一个完整的脚手架工具通常包含以下模块：

modern-cli/
├── 核心引擎 (Core Engine)
│   ├── 命令系统 (Commander)
│   ├── 模板系统 (Template System)
│   ├── 插件系统 (Plugin System)
│   └── 交互系统 (Interactive UI)
├── 模板仓库 (Template Repository)
└── 配置管理 (Configuration Management)

1. 项目初始化与基础结构

首先，我们创建一个基础的CLI项目结构：

mkdir modern-cli && cd modern-cli
npm init -y

安装核心依赖：

npm install commander inquirer chalk ora fs-extra download-git-repo handlebars

创建基础目录结构：

// modern-cli/
// ├── bin/
// │   └── cli.js        # CLI入口文件
// ├── lib/
// │   ├── core/
// │   │   ├── Creator.js # 项目创建器
// │   │   └── Template.js # 模板管理器
// │   ├── utils/
// │   │   └── logger.js  # 日志工具
// │   └── commands/      # 命令模块
// ├── templates/         # 模板目录
// └── package.json

2. CLI入口与命令系统

使用 commander 构建命令系统：

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

const { program } = require('commander');
const pkg = require('../package.json');
const createCommand = require('../lib/commands/create');

program
  .version(pkg.version)
  .description('Modern Frontend Scaffolding Tool');

// 创建项目命令
program
  .command('create <project-name>')
  .description('Create a new project')
  .option('-t, --template <template>', 'Specify template name')
  .option('-f, --force', 'Overwrite target directory if it exists')
  .action((projectName, options) => {
    createCommand(projectName, options);
  });

// 列出可用模板命令
program
  .command('list')
  .description('List all available templates')
  .action(() => {
    // 实现模板列表展示
    console.log('Available templates:');
    console.log('- react-ts: React + TypeScript');
    console.log('- vue3-ts: Vue 3 + TypeScript');
    console.log('- nextjs: Next.js fullstack');
  });

program.parse(process.argv);

在 package.json 中添加bin配置：

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

3. 智能模板系统实现

模板系统是脚手架的核心，支持本地模板和远程Git仓库模板：

// lib/core/Template.js
const fs = require('fs-extra');
const path = require('path');
const download = require('download-git-repo');
const handlebars = require('handlebars');
const chalk = require('chalk');
const ora = require('ora');

class Template {
  constructor() {
    this.templateDir = path.resolve(__dirname, '../../templates');
    this.remoteTemplates = {
      'react-ts': 'github:your-org/react-ts-template',
      'vue3-ts': 'github:your-org/vue3-ts-template',
      'nextjs': 'github:your-org/nextjs-template'
    };
  }

  // 获取可用模板列表
  async getAvailableTemplates() {
    const localTemplates = await this.getLocalTemplates();
    return {
      local: localTemplates,
      remote: Object.keys(this.remoteTemplates)
    };
  }

  // 下载远程模板
  async downloadTemplate(templateName, targetDir) {
    const spinner = ora(`Downloading template: ${templateName}`).start();
    
    return new Promise((resolve, reject) => {
      const repoUrl = this.remoteTemplates[templateName];
      if (!repoUrl) {
        spinner.fail(`Template ${templateName} not found`);
        reject(new Error(`Template ${templateName} not found`));
        return;
      }

      download(repoUrl, targetDir, { clone: true }, (err) => {
        if (err) {
          spinner.fail(`Download failed: ${err.message}`);
          reject(err);
        } else {
          spinner.succeed('Template downloaded successfully');
          resolve();
        }
      });
    });
  }

  // 渲染模板文件（支持变量替换）
  async renderTemplateFiles(targetDir, answers) {
    const files = await this.getAllFiles(targetDir);
    
    for (const file of files) {
      // 跳过node_modules和.git目录
      if (file.includes('node_modules') || file.includes('.git')) {
        continue;
      }

      const content = await fs.readFile(file, 'utf-8');
      
      // 检查是否是Handlebars模板
      if (content.includes('{{')) {
        const template = handlebars.compile(content);
        const rendered = template(answers);
        await fs.writeFile(file, rendered, 'utf-8');
        
        // 重命名.hbs文件
        if (file.endsWith('.hbs')) {
          const newPath = file.replace('.hbs', '');
          await fs.move(file, newPath);
        }
      }
    }
  }

  // 获取目录下所有文件
  async getAllFiles(dir) {
    const items = await fs.readdir(dir);
    let files = [];
    
    for (const item of items) {
      const fullPath = path.join(dir, item);
      const stat = await fs.stat(fullPath);
      
      if (stat.isDirectory()) {
        const subFiles = await this.getAllFiles(fullPath);
        files = files.concat(subFiles);
      } else {
        files.push(fullPath);
      }
    }
    
    return files;
  }
}

module.exports = Template;

4. 交互式项目创建器

使用 inquirer 实现交互式问答，收集项目配置：

// lib/core/Creator.js
const fs = require('fs-extra');
const path = require('path');
const inquirer = require('inquirer');
const chalk = require('chalk');
const Template = require('./Template');

class Creator {
  constructor(projectName, options) {
    this.projectName = projectName;
    this.options = options;
    this.targetDir = path.resolve(process.cwd(), projectName);
    this.template = new Template();
    this.answers = {};
  }

  async create() {
    // 检查目标目录是否存在
    await this.checkTargetDir();
    
    // 收集用户输入
    await this.promptUser();
    
    // 选择并下载模板
    await this.selectAndDownloadTemplate();
    
    // 渲染模板
    await this.renderTemplate();
    
    // 安装依赖
    await this.installDependencies();
    
    // 显示成功信息
    this.showSuccessMessage();
  }

  async checkTargetDir() {
    const exists = await fs.pathExists(this.targetDir);
    
    if (exists) {
      if (this.options.force) {
        console.log(chalk.yellow(`Removing existing directory: ${this.targetDir}`));
        await fs.remove(this.targetDir);
      } else {
        const { action } = await inquirer.prompt([
          {
            name: 'action',
            type: 'list',
            message: `Target directory ${chalk.cyan(this.targetDir)} already exists. Pick an action:`,
            choices: [
              { name: 'Overwrite', value: 'overwrite' },
              { name: 'Merge', value: 'merge' },
              { name: 'Cancel', value: false }
            ]
          }
        ]);

        if (!action) {
          process.exit(1);
        } else if (action === 'overwrite') {
          console.log(chalk.yellow('Removing existing directory...