TerraFE 脚手架开发实战系列（一）：项目架构设计与技术选型

前言

在前端开发中，项目初始化往往是一个重复且繁琐的过程。每次新建项目都需要配置 webpack、安装依赖、设置目录结构等，这些重复性工作不仅浪费时间，还容易出错。为了解决这个痛点，我决定开发一个现代化的前端脚手架工具 —— TerraFE。

本系列文章将完整记录 TerraFE 的开发过程，从架构设计到代码实现，希望能为想要开发 CLI 工具的同学提供一些参考和启发。

项目背景与目标

痛点分析

重复搭建：每次新建项目都要重复搭建相同的基础结构和配置
模板分散：优质的项目模板分散在各个 GitHub 仓库，难以发现和管理
手动配置：需要手动修改 package.json 等配置文件，容易出错且效率低下
包管理器选择：不同项目使用不同的包管理器，缺乏智能化的自动检测和选择

项目目标

TerraFE 旨在成为一个：

简单易用的前端项目脚手架工具
智能化的 GitHub / Gitlab 模板拉取工具
交互式的项目配置定制系统
高效的模板缓存管理机制

核心功能设计

1. 项目创建功能

# 基础创建命令（交互式）
terrafe create my-project# 指定内置模板
terrafe create my-project -t vite-react-ts# 指定 GitHub 仓库
terrafe create my-project -r owner/repo# 快速创建（跳过交互）
terrafe create my-project -y --template vite-vue-ts

2. 模板管理系统

# 列出所有可用模板
terrafe template list# 按类别列出模板
terrafe template list --category official# 添加自定义模板
terrafe template add my-template owner/repo# 删除自定义模板
terrafe template remove my-template# 搜索模板
terrafe template search react# 查看模板详情
terrafe template info vite-react-ts

3. 配置管理

# 查看所有配置
terrafe config list# 获取单个配置值
terrafe config get user.author# 设置配置值
terrafe config set packageManager pnpm# 删除配置
terrafe config delete user.email# 重置所有配置
terrafe config reset --force# 导出配置到文件
terrafe config export config.json# 从文件导入配置
terrafe config import config.json

技术栈选型

核心技术栈

技术	版本	选择理由
Node.js	>=16.0.0	现代 Node.js 特性支持，ES 模块原生支持
ES Modules	Native	更好的模块化，面向未来的标准
Commander.js	^14.0.0	成熟的命令行框架，API 简洁
Inquirer.js	^9.2.11	强大的交互式命令行工具
Chalk	^5.4.1	终端颜色输出，提升用户体验

工具库选择

工具	用途	选择原因
fs-extra	文件操作	比原生 fs 更强大，支持 Promise
download-git-repo	Git 仓库下载	专门用于下载 Git 仓库的轻量库
ora	加载动画	美观的终端加载提示
handlebars	模板引擎	强大的模板变量替换能力
validate-npm-package-name	包名验证	NPM 官方包名验证库

开发工具

工具	用途
Jest	单元测试框架
ESLint	代码质量检查
Prettier	代码格式化
Husky	Git Hooks 管理

项目架构设计

目录结构

terrafe/
├── bin/                    # 可执行文件
│   └── index.js           # CLI 入口文件
├── lib/                   # 核心代码
│   ├── commands/          # 命令实现
│   │   ├── create.js      # create 命令
│   │   ├── config.js      # config 命令
│   │   └── template.js    # template 命令
│   ├── core/              # 核心模块
│   │   ├── Generator.js   # 项目生成器
│   │   ├── Template.js    # 模板管理
│   │   └── Config.js      # 配置管理
│   ├── utils/             # 工具函数
│   │   ├── logger.js      # 日志工具
│   │   ├── file.js        # 文件操作
│   │   └── validate.js    # 验证工具
│   └── cache/             # 缓存管理
├── templates/             # 内置模板
├── __tests__/            # 测试文件
├── docs/                 # 文档
└── package.json

核心模块设计

1. 命令层（Commands）

负责处理用户输入的命令，解析参数，调用核心模块。

2. 核心层（Core）

Generator：项目生成器，负责整个项目创建流程
Template：模板管理器，处理模板的下载、缓存、解析
Config：配置管理器，处理用户配置的存储和读取

3. 工具层（Utils）

提供各种工具函数，如文件操作、日志输出、验证等。

4. 缓存层（Cache）

管理下载的模板缓存，提升重复使用时的性能。

设计原则

1. 单一职责原则

每个模块只负责一个特定的功能，确保代码的清晰和可维护性。

2. 开放封闭原则

通过配置化的模板系统支持扩展，便于添加新的项目模板和功能。

3. 依赖倒置原则

高层模块不依赖低层模块，都依赖于抽象。

4. 用户体验优先

清晰的错误提示
美观的界面输出
智能的默认选择
完善的帮助文档

开发环境搭建

1. 初始化项目

# 创建项目目录
mkdir terrafe && cd terrafe# 初始化 package.json
npm init -y# 设置 ES 模块
echo '{"type": "module"}' > .package.json.tmp
jq -s '.[0] * .[1]' package.json .package.json.tmp > package.json.new
mv package.json.new package.json
rm .package.json.tmp

2. 安装依赖

# 核心依赖
npm install commander inquirer chalk fs-extra download-git-repo ora handlebars validate-npm-package-name# 开发依赖
npm install --save-dev jest @jest/globals eslint prettier husky

3. 配置 package.json

{"name": "terrafe","version": "1.0.0","description": "TerraFE 是一个现代化 CLI 工具，让开发者通过一条命令即可创建定制化的前端项目架构","main": "index.js","type": "module","bin": {"terrafe": "./bin/index.js"},"scripts": {"dev": "node bin/index.js","test": "node --experimental-vm-modules node_modules/jest/bin/jest.js","test:watch": "npm test -- --watch","test:coverage": "npm test -- --coverage"},"engines": {"node": ">=16.0.0"}
}