从零开始制作 CLI 工具:快速创建项目脚手架
在现代前端开发中,项目初始化是一个高频且重复的操作。脚手架工具通过自动化项目结构的创建和基础配置的设定,显著提升开发效率。本教程将指导你从零开发一个 CLI(Command Line Interface)脚手架工具,它能够:
- 🚀 一键生成标准化的项目结构
- ⚙️ 根据用户选择动态配置项目
- 📁 自动安装依赖项
- 🔄 替换模板变量(如项目名称、作者等)
常见的脚手架工具如 create-react-app 或 vue-cli 都采用了类似原理。我们将创建一个简化版但功能完整的工具:create-my-app。
目录#
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. 最佳实践与常见陷阱#
最佳实践#
-
模板设计原则
- 保持模板最小化,只包含必要结构
- 使用
.ejs扩展名标识需渲染的文件 - 敏感信息用占位符代替(如
<%= API_KEY %>)
-
错误处理
process.on('unhandledRejection', (err) => { console.error(chalk.red(`[致命错误] ${err.message}`)); process.exit(1); }); -
性能优化
- 使用
fs.copy代替递归复制 - 并行化无依赖的操作
- 使用
常见陷阱#
| 问题 | 解决方案 |
|---|---|
| 权限不足 | 在package.json中设置"preferGlobal": true |
| 跨平台问题 | 使用path.join()代替字符串拼接路径 |
| 长耗时操作 | 添加进度指示器(如ora库) |
| 用户中断 | 监听SIGINT事件并清理临时文件 |
8. 发布到 npm 仓库#
-
登录 npm 账号
npm login -
添加文件白名单(防止发布模板文件)
// package.json "files": ["bin", "lib", "utils"] -
发布包
npm publish --access public -
用户全局安装
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 dev10. 结语#
通过本教程,你已经学会了如何:
- 构建专业的 CLI 工具架构
- 实现动态模板渲染功能
- 增加自动化依赖安装
- 应用错误处理和用户交互最佳实践
完整的示例代码可在 GitHub 获取:https://github.com/example/create-my-app(示例链接)
进阶建议:
- 增加模板远程更新功能
- 支持多源模板选择(GitHub/GitLab)
- 集成 CI/CD 配置生成
欢迎在评论区分享你创建的脚手架工具!🚀
11. 参考资源#
版权声明:自由转载-非商用-非衍生-保持署名(创意共享 3.0 许可证)