--- theme: orange highlight: a11y-dark --- ## 目录 1. 前言 2. cli脚手架核心功能 3. 优化cli脚手架功能 4. 发布cli到npm仓库 5. 验证脚手架功能 6. 总结 ## 一. 前言本文是专栏[《前端工程化》](https://juejin.cn/column/7092293219064479752)第7篇文章，会持续更新前端工程化方面详细高质量的教程。日常开发中，我们一直在用各种各样的脚手架，比如**vue-cli**,**@vue/cli**, **create-react-app**, **vite**还有其他很多社区的脚手架。通过这些脚手架我们可以很快的生成需要的项目模版，可以在此基础上快速的开发项目。通常在公司会根据公司的业务封装公司的各种项目模版, 为了方便使用，这时候就需要我们自己写一个**cli脚手架工具**来通过命令行的方式下载对应模版。本文将用详细的介绍用100行代码从零搭建一个具有完整的功能**cli脚手架**，从开发到发布到**npm仓库**使用，支持全局安装和非全局安装方法。相信学完本文章内容后，就可以在自己公司搭建**cli脚手架**，简化开发流程，也能提升自己的实际**工程化能力**。 ## 二. cli脚手架核心功能在工作中会经常使用到**cli脚手架**，对它的使用方式肯定不陌生，一般**cli脚手架**都有以下特点： * 可以通过**npm i xxx-cli -g**全局安装，然后在命令行直接使用安装的脚手架创建项目。 * 不全局安装可以通过**npx xxx-cli**直接从**npm**上访问该脚手架 * 在命令行执行脚手架时，可以在命令行直接**传参数**，脚手架会把参数传到配置中。 * 脚手架会出来**交互式**的**命令行**让我们选择不同的选项，并且获取到**选择的内容**。 * 最后根据最终选择结果生成下载**对应的模版**。有了上面的**cli脚手架**的核心逻辑，我们就来实现一个**cli脚手架**。 ### 2.1 创建脚手架项目 > window系统推荐用git命令行，有些命令window命令行不支持。新建一个**wuyou-cli**文件夹，在文件夹下执行**npm init -y**生成**package.json**文件 ```yaml mkdir wuyou-cli cd wuyou-cli npm init -y ``` ### 2.2 在全局命令行访问项目在**package.json**中有一个**bin**字段，该字段是一个对象，**key**是全局变量名称，**value**是触发全局变量时要执行的文件路径。配置**bin**对象后发布包到**npm**上面，全局安装该包时，就会把**bin**字段下对象的**key**注册到全局环境变量中。知道npm包管理的全局变量机制后，就可以进行配置了，在项目中新建**bin**目录，里面新建**cli.js**文件。这个**bin/cli.js**文件就是触发**wuyou-cli**全局变量时会执行的文件, 添加简单代码 ```js #! /usr/bin/env node console.log('wuyou-cli~~~~') ``` * **#! /usr/bin/env node**: 该字段是必须的，触发**wuyou-cli**时告诉操作系统用**node环境**来执行**cli.js**文件此时项目目录结构 ```yaml wuyou-cli ├─ bin │ └─ cli.js └─ package.json ``` 修改**package.json**文件，新增**bin**字段, 配置**wuyou-cli**变量，触发时执行文件地址指向`./bin/cli.js`。 ```json "bin": { "wuyou-cli": "./bin/cli.js" }, ``` 在本地调试的时候可以借助**npm link**把当前项目中**package.json**中的**bin**字段链接到全局变量。 ```yaml npm link // mac需要加sudo ``` 链接完成执行在命令行后执行**wuyou-cli**,就可以看到在**cli.js**中打印的内容了，代表链接成功了。可以修改一下**cli.js**中的内容，修改后再次在命令行执行**wuyou-cli**，可以看到此时打印的内容也是更新了。 ![1.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/334484ee3d434b9a8021467294411c73~tplv-k3u1fbpfcp-watermark.image?) 此时**npm**把**bin命令**链接到全局就成功了，此时如果把代码发布到**npm**上，执行**npm i wuyou-cli -g**全局安装**wuyou-cli**，就会把**wuyou-cli**自动链接到全局变量中。 ### 2.4 配置自定义交互式命令在使用**cli**脚手架的时候，经常会通过脚手架执行一些命令，比如`--version`, `--help`来查看版本和帮助信息, 以及常见的**create**或**init**命令来触发创建项目模版交互，如果自己写的话会比较耗费时间，这个时候可以直接用社区已经封装好的[commander](https://www.npmjs.com/package/commander)来完成这件事，先进行安装： ```yaml npm i commander -S ``` 安装好后先简单测试一下，添加一个检测当前脚手架版本的功能，一般可以通过`-V`或者`--version`来查看。在`./bin/cli.js`里面添加代码: ```js #! /usr/bin/env node const program = require('commander') const package = require('../package.json') // 定义当前版本 program.version(**v${package.version}**) // 解析用户执行命令传入参数 program.parse(process.argv) ``` 保存代码后在命令行输入： ```yaml wuyou-cli --version ``` 会看到命令行出现了版本号。 ![1.1.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/1ce01c9eed2444bf8f993223479ce1db~tplv-k3u1fbpfcp-watermark.image?) ### 2.5 处理创建模版命令接下来就要处理用户创建模版的命令，我们规定当用户在命令行输入wuyou-cli create的时候触发创建模版操作，触发后第一步要输入项目名称，第二步是选择模版，选择完模版后进行创建操作。需要能处理用户在命令行的输入，就可以用[inquirer](https://www.npmjs.com/package/inquirer)模块，inquirer是一个交互式命令行工具库，用于与用户进行交互，最新版本需要**import**引入，所以本文用的`^8.2.5`版本，安装依赖： ```yaml npm i inquirer@^8.2.5 -S ``` 然后在**bin/cli.js**里面添加代码 ```js #!/usr/bin/env node const program = require('commander'); const inquirer = require('inquirer'); const package = require("../package.json"); // 定义当前版本 program.version(**v${package.version}**); program .command('create') .description('创建模版') .action(async () => { const { name } = await inquirer.prompt({ type: 'input', name: 'name', message: '请输入项目名称：' }) console.log("项目名称：", name) }); program.parse(process.argv); ``` 以上代码使用了 **commander** 库来解析命令行参数，并定义了 **create** 命令。在 **create** 命令被调用时，会使用 **inquirer** 库与用户进行交互，获取用户输入的项目名称。以上代码中，我们使用了**inquirer**的**input**问题类型。根据不同的问题类型，需要提供不同的参数和答案类型，**inquirer**字段描述： * **type**: 问题类型，可以是 **input**（输入框）、**list**（列表选择框）、**confirm**（二选一选择框）等 * **name**: 问题名称，用于标识答案对象中对应的属性名 * **message**: 问题描述，将会作为问题提示信息展示给用户 * **choices**: 选项列表，只有当问题类型为 list 时才需要提供代码写好后，在命令行执行： ```yaml wuyou-cli create ``` 如下图，执行后会出现请输入**项目名称**，输入名称后按**回车**，就可以看到拿到了用户输入的**项目名称**。 ![1.2.png](https://p1-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b0b8d449593949bf9aa3b81073cfad77~tplv-k3u1fbpfcp-watermark.image?) ### 2.6 实现选择项目模版获取到用户输入的项目名称后，后面要做的事情就是让用户选择要下载的模版，然后把模版代码输出到用户输入的项目名称文件夹中。下载模版有两种方式： 1. 把模版代码放在**cli脚手架**目录里面，然后把模版代码拷贝到用户目标目录中。 2. 把模版放在远程**git**上面，选择完模版从**git**远程拉取代码到用户目标目录中。第一种下载模版速度快，但每次模版变动都要升级脚手架版本，不太灵活，所以这里采用第二种方法。模版要换成真实的**git地址**，本文模版地址采用我原先三篇工程化文章中的代码模版： * webpack5-react-ts：[【前端工程化】webpack5从零搭建完整的react18+ts开发和打包环境](https://juejin.cn/post/7111922283681153038) * react18-vite2-ts :[【前端工程化】配置React+ts项目完整的代码及样式格式和git提交规范](https://juejin.cn/post/7101596844181962788) * dumi2-demo: [【前端工程化】带你使用dumi2一步一步搭建自己的React组件库和函数库](https://juejin.cn/post/7222804347830206525) 在**bin**目录下新建**templates.js**文件，添加以下代码： ```js /** 暴露模版代码 */ module.exports = [ { name: 'webpack5-react-ts', value: 'https://github.com:guojiongwei/webpack5-react-ts' }, { name: 'react18-vite2-ts', value: 'https://github.com:guojiongwei/react18-vite2-ts' }, { name: 'dumi2-demo', value: 'https://github.com:guojiongwei/dumi2-demo' } ] ``` > 注意模版地址部分，域名和模版地址之间是用冒号:隔开的，不是斜杠/，这个是下一节下载git仓库代码模版所用到的库[download-git-repo](https://www.npmjs.com/package/download-git-repo)的规则。 > > 实际项目中要根据自己的需求配置不同的模版，比如gitlab，gitee等，文章后面也会换成接口动态请求。 **支持gitee-2023-07-21补充** 下载**gitee**模版需要把路径设置为`direct:https://gitee.com/xxx/xxx.git`，然后使用下载模版工具**downloadGitRepo**时(下面会讲)，需要带上`{ clone: true }`参数 ```js downloadGitRepo(projectTemplate, dest, { clone: true }, (err) => {}) ``` 定义好模版后在**bin/cli.js**添加选择模版，选择模版是让用户选择列表，需要用**inquirer**库的**list**类型： ```js // ... const templates = require('./templates.js') program .command('create') .description('创建模版') .action(async () => { // ...省略输入项目名称代码 // 新增选择模版代码 const { template } = await inquirer.prompt({ type: 'list', name: 'template', message: '请选择模版：', choices: templates // 模版列表 }) console.log('模版：', template) }); program.parse(process.argv); // ... ``` 代码保存后再次在终端输入**wuyou-cli create**，就可以选择真实的模版数据，拿到对应项目的**git**地址。 ![2.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e46944ec964d492cb606214ef29b5e37~tplv-k3u1fbpfcp-watermark.image?) ![2.1.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bb046f60f5ac40bbbe0bcf8d84c9eb69~tplv-k3u1fbpfcp-watermark.image?) ### 2.7 实现下载模版拿到用户选择的模版地址后，就要根据用户输入的项目名称，把指定的项目模版下载到对应项目文件夹中，实现下载git项目模版的功能使用[download-git-repo](https://www.npmjs.com/package/download-git-repo)依赖来完成，安装依赖： ```yaml npm i download-git-repo -S ``` **download-git-repo**的语法 ```js const downloadGitRepo = require('download-git-repo') downloadGitRepo('项目git地址', '目标文件夹', function(err) { if (err) { console.log('下载失败', err) } else { console.log('下载成功') } }) ``` > 默认会拉取**master**分支的代码，如果想从其他分支拉取代码，可以在git地址后面添加`#branch`选择分支。项目的**git**地址在选择完模版时可以获取到，现在要获取目标文件夹，目标目录应该是用户执行命令行所在位置下的项目名称文件夹。可以通过`process.cwd()`方法来获取用户执行命令行所在的目录位置，再加上用户输入的项目名称，所以目标文件夹路径应该为： ```js const path = require('path') // 目标文件夹 = 用户命令行所在目录 + 项目名称 const dest = path.join(process.cwd(), name) ``` 项目**git**地址和目标文件夹都拿到后，接下来，我们需要在获取到模版地址后去进行下载模版的操作，修改**bin/cli.js**文件，添加下载模版代码： ```js // 引入 const path = require("path") const downloadGitRepo = require('download-git-repo') // ... // 获取目标文件夹 const dest = path.join(process.cwd(), name) // 开心下载模版 downloadGitRepo(template, dest, (err) => { if (err) { console.log('创建模版失败', err) } else { console.log('创建模版成功') } }) ``` 代码写好后，我们再在命令行输入 ```yaml wuyou-cli create ``` 会出现输入项目名称和选择模版操作，选择完模版后就会自动把模版下载到我们输入到项目名称文件夹里面，如下图： ![4.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dd227b16fd9d4067b485032c6d4e3dc7~tplv-k3u1fbpfcp-watermark.image?) 到这里一个基础的**cli命令行脚手架**就创建好啦! ## 三. 优化cli脚手架上一节已经实现了一个基础的脚手架功能，但一些细节体验不够完善，我们需要完善一下。 ### 3.1 优化下载模版时等待交互在上面下载模版的时候，由于是从**github**下载的模版，有时候网络不好，下载时间会久一些，如果什么都不做看着像卡住一样。我们可以添加一下命令行**loading动画**来提升用户体验。可以用[ora](https://www.npmjs.com/package/ora)这个库来实现这个功能，**ora**是一个命令行的**loading动画库**，最新版本需要**import**引入，所以本文用的`^5.4.1`版本，安装依赖： ```yaml npm i ora@^5.4.1 -S ``` 安装好后修改**bin/cli.js**代码，在**downloadGitRepo**下载模版之前调用展示**loading**代码，在下载模版结束后，停止**loading**展示。 ```js // bin/cli.js // ... const ora = require('ora') // 引入ora // 定义loading const loading = ora('正在下载模版...') // 开始loading loading.start() // 开始下载模版 downloadGitRepo(template+, dest, (err) => { if (err) { loading.fail('创建模版失败：' + err.message) // 失败loading } else { loading.succeed('创建模版成功!') // 成功loading } }) ``` **ora**的**loading**代码添加好后，再次执行**wuyou-cli create**，输入名称，选择模版，下载的时候就会出现动态的**loading**和提示语，让用户感知到正在下载模版，提升使用体验。 ![5.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b632730905f2476f9fb2d2d51da43571~tplv-k3u1fbpfcp-watermark.image?) ### 3.2 添加可操作命令提示现在我们的**cli**只有执行**wuyou-cli --version**和**wuyou-cli create**创建模版时命令行才有反应，有时候用户想查询都有哪些命令可以操作，所以可以加一个`-help`或者`-h`命令时查询所有可执行的命令。 **program**提供了监听`--help`操作，在**bin/cli.js**中配置后用户执行`-h` 或者 `--help`都会触发，会自动把当前**program**注册的所有命令都打印到控制台，供用户查看。 ```js // bin/cli.js // ... program.on('--help', () => {}) // 添加--help ``` 添加好后再在命令输入命令： ```yaml wuyou-cli --help ``` 可以看到在控制台可以看到当前**cli脚手架**支持的**command**命令以及描述，可以很大的方便用户使用。 ![6.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/879241aebac1461b83d57e0805ba9ec3~tplv-k3u1fbpfcp-watermark.image?) ### 3.3 支持从命令行传参数上面用户输入项目名称和选择模版都是通过**wuyou-cli create**命令来触发的，也可以通过命令行参数形式直接项目传入名称和模版，就像[vite](https://vitejs.cn/vite3-cn/guide/#scaffolding-your-first-vite-project)一样，可以直接在命令行输入**项目名称**和**模版名称**。 ```yaml # npm 6.x npm create vite@latest my-vue-app --template vue # npm 7+, extra double-dash is needed: npm create vite@latest my-vue-app -- --template vue # yarn yarn create vite my-vue-app --template vue # pnpm pnpm create vite my-vue-app --template vue ``` 实现这个功能依然是使用**program**库，它提供了获取命令行参数的功能，在**create**后面加上`[projectName]`，可以获取命令传入的项目名称，配置`.option`可以获取到通过`-t`或`--template`传入的模版名称： ```js program .command('create [projectName]') // [projectName]是可选是必填 .option('-t, --template', '模版名称') // 配置项 --template xxx .description('创建项目') .action(async (projectName, options) => { // projectName: 项目名称 // options: 配置项 { template: string } }) ``` 知道实现机制后，就可以改**bin/cli.js**代码了： ```js // ... program .command("create [projectName]") .description("创建模版") .option('-t, --template