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"}
}
技術難點預估
1. GitHub 模板下載機制
如何穩定可靠地從 GitHub 倉庫下載模板，處理網絡異常和權限問題。
2. 交互式配置體驗
如何設計用戶友好的交互式命令行界面，提供清晰的選擇和配置流程。
3. 緩存管理機制
如何設計高效的本地緩存系統，平衡存儲空間和訪問速度。
4. 包管理器智能檢測
如何準確檢測和選擇最適合的包管理器（pnpm > yarn > npm）。
總結
本文介紹了 TerraFE 腳手架工具的項目背景、目標設計和技術選型。通過合理的架構設計和技術棧選擇，我們為后續的開發工作奠定了堅實的基礎。
在下一篇文章中，我們將開始實際的編碼工作，從 CLI 工具的基礎搭建開始，逐步實現各個功能模塊。
下期預告
《TerraFE 腳手架開發實戰系列（二）：CLI 工具基礎搭建》
- Commander.js 命令行框架的使用
- ES 模塊的導入導出機制
- 基礎的 create 命令實現
- 錯誤處理機制的建立
如果這篇文章對你有幫助，歡迎點贊和轉發。有任何問題或建議，歡迎在評論區討論！
