打造專屬 React 腳手架：從 0 到 1 開發 CLI 工具

前言:

在前端開發中，重復搭建項目環境是個低效的事兒。要是團隊技術棧固定（比如 React + AntD + Zustand + TS ），每次從零開始配路由、狀態管理、UI 組件，既耗時又容易出錯。這時候，自定義 CLI 腳手架?就派上大用場了 —— 一行命令就能生成標準化項目，直接進入業務開發！

本文就帶你從 0 到 1 開發一套 React 腳手架 CLI，實現 “拉取模板 + 初始化 Git + 自動裝依賴” 全流程，讓項目搭建像 “搭積木” 一樣簡單 ?

一、需求拆解：腳手架要解決什么問題？

我們的目標是做一個?“開箱即用” 的 React 腳手架，核心功能：

模板一鍵拉取：從 GitHub 倉庫拉取包含 React 路由、AntD 組件、Zustand 狀態管理的項目模板。
自動初始化流程：無需手動?git init、npm install，工具自動完成。
開發命令指引：安裝完直接提示啟動命令，無縫銜接開發。

二、技術選型：哪些工具能幫我們實現？

commander：解析命令行參數（定義?create <projectName>?命令）。
download-git-repo：從 Git 倉庫下載模板（支持 GitHub、GitLab 等）。
child_process：Node.js 內置模塊，執行終端命令（如?git init、npm install）。

三、代碼實現：一步步打造 CLI 工具

1. 初始化項目 & 安裝依賴

# 新建腳手架項目目錄
mkdir react-scaffold-cli
cd react-scaffold-cli# 初始化 package.json
npm init -y# 安裝核心依賴
npm install commander download-git-repo

2. 編寫 CLI 核心邏輯（`cli.js`）

#!/usr/bin/env node
const { program } = require("commander");
const download = require("download-git-repo");
const path = require("path");
const { execSync } = require("child_process");// 定義命令：react-scaffold create <projectName>
program.command("create <projectName>").description("創建 React + AntD + Zustand + TS 項目").action((projectName) => {// 1. 配置模板倉庫 & 目標路徑const repo = "github:jackywq/react-antd-zustand-scaffold#main"; const targetPath = path.join(process.cwd(), projectName); // 2. 從 Git 拉取模板download(repo, targetPath, {}, (err) => {if (err) {console.error("? 模板下載失敗：", err);return;}console.log("? 模板下載完成！");try {// 3. 初始化 Git 倉庫（解決 husky 依賴 .git 問題）console.log("📦 初始化 Git 倉庫...");execSync(`cd ${projectName} && git init`, { stdio: "inherit" });// 4. 自動安裝依賴console.log("📦 開始安裝依賴...");execSync(`cd ${projectName} && npm install`, { stdio: "inherit" });// 5. 提示啟動命令console.log("? 依賴安裝完成！");console.log(`? 項目創建成功，可執行：cd ${projectName} && npm run start`);} catch (installErr) {console.error("? 依賴安裝失敗：", installErr);}});});// 解析命令行參數，觸發對應邏輯
program.parse(process.argv);

3. 代碼逐行解析

（1）基礎配置：讓腳本可執行

#!/usr/bin/env node

這行是?Shebang 聲明，告訴系統 “用 Node.js 運行這個腳本”，這樣我們就能直接用?react-scaffold create ...?調用，無需手動輸入?node cli.js。

（2）依賴引入：工具的 “左臂右膀”

const { program } = require("commander"); // 解析命令行參數
const download = require("download-git-repo"); // 拉取 Git 模板
const path = require("path"); // 處理文件路徑
const { execSync } = require("child_process"); // 執行終端命令

commander：讓我們能定義?create?命令，解析用戶輸入的?projectName。
download-git-repo：從 GitHub 倉庫下載模板代碼（一行代碼實現?git clone?功能）。
child_process：執行?git init、npm install?等終端命令，自動化初始化流程。

（3）命令定義：告訴用戶怎么用

program.command("create <projectName>").description("創建 React + AntD + Zustand + TS 項目").action((projectName) => { ... });

command("create <projectName>")：定義?create?命令，<projectName>?是用戶要創建的項目名稱（必填）。
description(...)：添加命令描述，執行?react-scaffold --help?時會顯示。
action(...)：命令的 “執行邏輯”，用戶輸入?create my-app?時，就會觸發這里的代碼。

（4）核心流程：項目創建全自動化

// 模板倉庫地址（替換成你自己的 GitHub 倉庫！）
const repo = "github:jackywq/react-antd-zustand-scaffold#main"; 
// 目標路徑：當前目錄 + 項目名（如 ./my-app）
const targetPath = path.join(process.cwd(), projectName);

repo：格式是?github:用戶名/倉庫名#分支，指定從哪拉取模板。
targetPath：計算項目要創建的路徑（比如用戶當前在?~/projects，執行?create my-app?就會生成?~/projects/my-app）。

download(repo, targetPath, {}, (err) => { ... });

調用?download-git-repo?拉取模板，失敗會提示?模板下載失敗，成功則繼續執行初始化流程。

execSync(`cd ${projectName} && git init`, { stdio: "inherit" });
execSync(`cd ${projectName} && npm install`, { stdio: "inherit" });

git init：初始化 Git 倉庫（解決?husky?等工具依賴?.git?目錄的問題）。
npm install：自動安裝項目依賴（基于模板里的?package.json）。
{ stdio: "inherit" }：讓終端實時輸出命令執行日志（用戶能看到?git init、npm install?的過程）。

四、測試 & 發布：讓腳手架真正能用起來！

1. 本地測試：直接運行 CLI

# 在腳手架項目目錄執行
node cli.js create my-app

觀察終端輸出：
- 成功：模板下載完成！?→?初始化 Git 倉庫...?→?依賴安裝完成！
- 失敗：檢查網絡（能否訪問 GitHub）、模板倉庫地址是否正確。

2. 發布到 npm：讓所有人都能安裝

（1）修改?`package.json`，添加關鍵配置

{"name": "react-scaffold-cli","version": "1.0.0","bin": {"react-scaffold": "cli.js"  // 定義全局命令},"dependencies": {"commander": "^11.0.0","download-git-repo": "^3.0.2"}
}

bin：定義全局命令?react-scaffold，用戶安裝后可直接用?react-scaffold create ...?調用。
dependencies：聲明生產依賴（commander、download-git-repo?必須被安裝）。

（2）發布到 npm 倉庫

# 1. 登錄 npm（確保已注冊賬號）
npm login# 2. 發布腳手架
npm publish

發布成功后，任何人都能通過?npm install -g react-scaffold-cli?全局安裝你的腳手架！

五、優化 & 擴展：讓腳手架更強大

1. 模板倉庫替換：用自己的項目模板

把?repo?換成你自己的 GitHub 倉庫地址，比如：

const repo = "github:your-username/your-react-template#main";

模板倉庫里可以包含：

React 路由配置（react-router-dom）
AntD 基礎組件（Button、Layout?等）
Zustand 狀態管理示例（用戶登錄狀態、全局配置）

2. 增加交互：讓用戶選模板

如果想支持?多模板選擇（比如 “React + Vue + ...”），可以用?inquirer?實現交互：

npm install inquirer

const inquirer = require("inquirer");program.command("create <projectName>").action(async (projectName) => {// 讓用戶選擇模板const { template } = await inquirer.prompt([{type: "list",name: "template",message: "選擇項目模板",choices: ["react-antd", "vue-element", "next-js"]}]);// 根據選擇拼接不同的 repo 地址const repoMap = {"react-antd": "github:your-username/react-template#main","vue-element": "github:your-username/vue-template#main"};const repo = repoMap[template];// 后續流程和之前一樣...});

3. 錯誤處理：讓用戶更清楚哪里出錯了

如果下載模板失敗，可以細化錯誤提示：

download(repo, targetPath, {}, (err) => {if (err) {if (err.message.includes("not found")) {console.error("? 模板倉庫不存在，請檢查地址！");} else if (err.message.includes("network")) {console.error("? 網絡錯誤，請檢查網絡連接！");} else {console.error("? 模板下載失敗：", err);}return;}// ...后續流程
});