【手把手】15分钟搭一个企业级脚手架

Love The Way You Lie 2023-05-29 03:54 8阅读 0赞

### 1 写在前面的话 ###

搭一个脚手架，考验了你的 nodejs 水平、工程化能力、以及工具服务的设计能力，是前端进阶不可或缺的过程

笔者在开发 cli 的过程中，调研流行的 cli 并形成最佳实践，本文旨在用最短的篇幅实现主要功能，揭露核心原理，同时提供 demo 仓库与大家学习探讨。

通篇阅读大约需要 10 分钟，基于本教程自己撸一个 cli 大约需要花费 15 分钟

> 仓库清单： [文章博客][Link 1] | [脚手架-全局命令包][-] | [脚手架-模板插件包][- 1] | [脚手架-构建插件包][- 2]

### 2 脚手架的雏形 ###

其实脚手架的初衷，就是提供一个最佳实践的基础模板，因此**模板拷贝**是其核心功能

几年前我曾写过一个极简的脚手架，大该干了这么一件事儿

1.  npm publish 一个全局安装的包
2.  执行命令时，wget 我云服务上的一个压缩包，并在当前文件夹下解压

一个命令，就可以把我预设的完整的工程目录创建好，特别方便效率。

我想，这应该算是一个雏形脚手架吧

### 3 脚手架需要考虑的 ###

上面雏形脚手架可以很好的服务于个人需求，但是毕竟过于干瘪和简陋，要想成为被大家广泛接受的工具，还需要完善。

大家熟知的 `vue-cli` `create-react-app` `@tarojs/cli` `umi` 最基本功能：首先提出一些列**问题选项**，然后**为你的新建项目提供一份模板**并安装依赖，再提供**调试构建**命令

没错，最核心的部分就是这个思路；但如果要做成一个可伸缩的、用户友好的，还需考虑这些需求：

*  模板支持版本管理
 *  支持扩展新模板
 *  自动检测版本更新
 *  根据用户选择，生成个性化模板
 *  友好的UI界面
 *  构建功能独立，可因模板而异 (如区分H5/PC/weapp/RN)
 *  多人合作项目，能确保构建结果一致

看起来信息量有点大，但其实都并不晦涩，我们一一说明一下意图

#### 3.1 模板支持版本管理 ####

比如用户使用 v1.0.0 的模板创建了项目，半年后，已经迭代升级到了 v2.0.0。我们需要依旧能够找到 v1.0.0 版本，因为老用户不想或者不方便升级。

像我之前的雏形脚手架，将模板打一个压缩包放在云服务器上是不可行的，一旦更新就全量替换了

npm 仓库天然支持版本管理，因此将模板发布到 npm 上自然解决了这个问题 *(非开源项目，可考虑自建仓库或者私有的仓库)*

#### 3.2 支持扩展新模板 ####

比如我们一开始我们的脚手架支持 H5 的模板。

半年后，随着业务发展，需支持微信小程序的模板。

此时，我们无需额外再开发一个 cli，而是让 cli 一开始设计的就支持扩展，这符合了开放封闭的设计原则

#### 3.3 自动检测版本更新 ####

npm 提供了一些命令来检测包的版本，比如你 `npm view react version` 返回 `16.9.0`，告知你最新版本

借此，可以判断用户目前安装的是否最新版本，并提示用户更新

#### 3.4 根据用户选择，生成个性化模板 ####

模板虽说是为了统一，但也要在统一中支持差异，可通过问询用户，来提供差异化支持，比如：

![Image 1][]

这些问询的结果，将影响我们最终的模板，比如我们根据是否 TypeScript 会在两套预设的模板中选一个套，将用户输入的「项目介绍」插入 package.json 的 description 字段等等

#### 3.5 友好的UI界面 ####

合适的格式、颜色、字体、进图条等，给与用户良好的信息反馈

下文会介绍一些常用的库，来提供这些功能

#### 3.6 构建功能独立，可因模板而异 ####

我们通常使用 webpack 来构建/调试，对于不同的模板，构建流程存在较大差异，我们需要支持为不同的模板配置不同的构建

因此构建能力也被抽离成单独的 npm 包，模板中可指定其构建包

#### 3.7 多人合作项目，能确保构建结果一致 ####

因为存在多版本，我们需要约束，让所有项目的贡献者的产出是一致的

其核心原则就是：针对那些可能导致差异的因素，我们都收录到工程中，让 git 仓库记录，从而实现同样，因此，现在流行的脚手架，如 `umi` `taro`，都将 **构建能力 local 化到本地工程中**，后续会做详细阐明

### 4 脚手架的三类包 ###

一个被实践检验，能够符合上述需求的脚手架架构，其实非常简单，首先我们拆分成三类 npm 包：

<table> 
 <thead> 
  <tr> 
   <th>包</th> 
   <th>功能</th> 
   <th>安装位置</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>全局命令包</td> 
   <td>就像一个大脑，负责响应全局命令，并进行调度</td> 
   <td>全局包路径</td> 
   <td>global 安装，提供全局命令</td> 
  </tr> 
  <tr> 
   <td>模板插件包</td> 
   <td>初始化工程所拷贝的模板</td> 
   <td>某个约定路径，如 <code>~/.maoda</code></td> 
   <td>模板可随业务扩展</td> 
  </tr> 
  <tr> 
   <td>构建插件包</td> 
   <td>提供构建(webpack)能力</td> 
   <td>工程内 <em>(目前主流脚手架都改用此方案)</em></td> 
   <td>不同模板可使用同一构建包，也可不同</td> 
  </tr> 
 </tbody> 
</table>

> 注：构建插件包，早期很多脚手架都把它放在工程外，比如放在全局，优势是多工程可复用一套 webpack 能力，但弊端也暴露出来，即在多人协同开发的项目中，由于构建插件包不在工程里没能被 git 仓库收录，导致一些不可预期的差异结果。

其调度关系如下：

![1][]

### 5 全局命令包 ###

前面说了一通理论，下面开始正式搭建

全局命令包的功能：负责接收全局命令，并调度。

比如我做的 cli 的模板 demo cli-tpl

npm i cli-tpl -g
    # 或 yarn global add cli-tpl
    复制代码

全局安装后，暴露出一个 `dcli` 命令 *(自己随便取的名字)*，该命令有以下典型功能：

> 暴露全局命令通过 package.json 中 bin 来指定，可参考我的 demo

<table> 
 <thead> 
  <tr> 
   <th>命令</th> 
   <th>效果</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>dcli install [pkgName]</code></td> 
   <td>安装一个「模板插件包」到 <code>~/.maoda</code> 路径，如果已经安装再执行，则询问更新到最新版，如安装 <code>dcli install gen-tpl</code></td> 
  </tr> 
  <tr> 
   <td><code>dcli init</code></td> 
   <td>以某个模板初始化一个新工程，执行后会让你从已装模板里选择</td> 
  </tr> 
  <tr> 
   <td><code>dcli build</code></td> 
   <td>在工程根目录执行 <em>(或写进工程的 scripts 里)</em>，尝试读取工程依赖的「构建插件包」并执行构建</td> 
  </tr> 
  <tr> 
   <td><code>dcli dev</code></td> 
   <td>与 <code>dcli build</code> 类似，只不过是执行调试</td> 
  </tr> 
 </tbody> 
</table>

#### 5.1 cli 开发中值得收藏的一些第三方调料包 ####

<table> 
 <thead> 
  <tr> 
   <th>重要性</th> 
   <th>包名称</th> 
   <th>功能</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/minimist" rel="nofollow">minimist</a></td> 
   <td>解析用户命令，将 process.argv 解析成对象</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/fs-extra" rel="nofollow">fs-extra</a></td> 
   <td>对 fs 库的扩展，支持 promise</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/chalk" rel="nofollow">chalk</a></td> 
   <td>让你 console.log 出来的字带颜色，比如成功时的绿色字</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/import-from" rel="nofollow">import-from</a></td> 
   <td>类似 require，但支持指定目录，让你可以跨工程目录进行 require，比如全局包想引用工程路径下的内容</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/resolve-from" rel="nofollow">resolve-from</a></td> 
   <td>同上，只不过是 require.resolve</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/inquirer" rel="nofollow">inquirer</a></td> 
   <td>询问用户并记录反馈结果，界面互动的神器</td> 
  </tr> 
  <tr> 
   <td>必要</td> 
   <td><a href="https://www.npmjs.com/package/yeoman-environment" rel="nofollow">yeoman-environment</a></td> 
   <td>【核心】用于执行一个「模板插件包」，后文详细描述</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/easy-table" rel="nofollow">easy-table</a></td> 
   <td>类似 console.table，输出漂亮的表格</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/ora" rel="nofollow">ora</a></td> 
   <td>提供 loading 菊花</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/semver" rel="nofollow">semver</a></td> 
   <td>提供版本比较</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/figlet" rel="nofollow">figlet</a></td> 
   <td>console.log出一个漂亮的大logo</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/cross-spawn" rel="nofollow">cross-spawn</a></td> 
   <td>跨平台的child_process (跨 Windows/Mac)</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/osenv" rel="nofollow">osenv</a></td> 
   <td>跨平台的系统信息</td> 
  </tr> 
  <tr> 
   <td>锦上添花</td> 
   <td><a href="https://www.npmjs.com/package/open" rel="nofollow">open</a></td> 
   <td>跨平台打开 app，比如调试的时候开打 chrome</td> 
  </tr> 
 </tbody> 
</table>

#### 5.2 命令解析与分发 ####

命令的解析与分发，是「全局命令包」的核心功能，其过程比较简单。大家也可以直接看仓库 [cli-tpl][-] *(全部功能压缩到大约300行代码)*

1.  cli 版本更新判断：
    
     *  先获取本 package.json 中的 version
     *  再通过 `npm view cli-tpl version` 命令查询当前 npm 库最新版本
     *  两者比较得出结论，提醒用户更新
2.  解析用户命令
    
     *  通过 process.argv\[2\] 获取到用户执行的实际命令，比如 `dcli install` 可拿到 `install` *(正式版推荐使用 minimist 解析参数)*
3.  处理命令
    
     *  比如 install 命令，则通过 require 动态映射 `install.js` 文件来处理该逻辑
     *  注：require 支持动态名称，如 `require('./scripts/' + command)` 这样，如果 command 是 `install` 则映射执行 `script/install.js` 文件

接下来我们看下 4 个核心命令，主要是：

<table> 
 <thead> 
  <tr> 
   <th>命令</th> 
   <th>效果</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>install</td> 
   <td>帮用户安装/升级一个「模板插件包」</td> 
  </tr> 
  <tr> 
   <td>init</td> 
   <td>帮用户初始化一个工程，并拷贝模板</td> 
  </tr> 
  <tr> 
   <td>build</td> 
   <td>调用工程中的「构建插件包」，帮用户webpack构建</td> 
  </tr> 
  <tr> 
   <td>dev</td> 
   <td>帮用户启动 devServer 进行调试</td> 
  </tr> 
 </tbody> 
</table>

下面逐一阐述每个命令的实现过程以及效果：

#### 5.3 **install**命令：安装一个「模板插件包」 ####

install 意思就是把这个模板插件包下载到硬盘；此处我做了一个最小功能的 demo 包 [gen-tpl][- 1] *(后文详细分解)* 来辅助讲解

dcli install gen-tpl
    复制代码

![1 1][]

核心处理流程如下：

1.  先判断是否硬盘缓存目录 `~/.maoda` 下是否已经有安装过 `gen-tpl` 包
    
     *  如果没有，则接下来进行安装 *(相当于在 `~/.maoda` 目录下执行 npm install)*
     *  如果有，且版本低，则提示升级
     *  如果有，且版本最新，则不作为
2.  安装过程即 `execSync('npm i gen-tpl@latest -S', { cwd: '~/.maoda' })`

> 我们可以为「模板插件包」的名称做一个约定，即具备固定的前缀，诸如 `gen-xxx`

#### 5.4 **init**命令: 选一个「模板插件包」来初始化一个新工程 ####

这是一个脚手架高频而核心的功能

dcli init
    复制代码

![1 2][]

此时会分发去执行 `script/init.js` 文件，我们看看其逻辑

1.  查询硬盘缓存目录 `~/.maoda` 下的 `package.json` 文件，读取其中 `dependacies` 字段，拿到已安装的「模板插件包」
    
     *  如果一个都没安装，则提示用户要先 install
2.  让用户选择一套模板
    
     *  利用 `inquery` 库发起对话，罗列出已装模板，让用户选择，比如上图的 `gen-pc` `gen-h5` `gen-tpl`
3.  触发模板初始化流程
    
     *  比如用户选择了 `gen-tpl` 这个模板，则用 `yeoman-environment` 这个库去执行缓存目录里的这个包 `~/.maoda/gen-tpl/index.js`
     *  注：这里相当于跨目录的两个 js 文件引用执行，用到了之前说的 `import-from` 这个库
4.  「模板插件包」被执行，则启动了常规的模板拷贝过程 *(后面展开细说)*

> 这里直接用包名称做选项，为了演示更直观，实际通常用包的 description 做选项，更友好一些，比如 `gen-pc` 包可能描述为 `生成PC模板`

#### 5.5 **build**命令：在工程里执行构建 ####

dcli build
    复制代码

![1 3][]

1.  确定工程目录
    
     *  工程目录即执行目录，通过 process.cwd() 获取
2.  读取该工程所用的构建插件
    
     *  读取工程中约定的配置文件，本demo中为 `maoda.js` *(采用约定式的配置，`类似 webpack.config.js` `.babelrc` `.prettierrc`)*
     *  读取 `maoda.js` 中 `builder` 配置项 *(即指定的构建插件包)*，比如本 demo 中指定为 `build-tpl`
     *  如果有的话，读取自定义 webpack 配置 *(约定为 webpackCustom 字段，后续会被合并/覆盖到默认 webpack 配置上)*
3.  使用制定的构建插件包来进行 webpack 打包
    
     *  判断工程中是否已经安装 `build-tpl`
     *  未安装，则在工程中路径中执行 `npm install` *(或 yarn add，此处有个小技巧，可根据用户工程中 lock 文件的类型，判断用户使用的 npm 还是 yarn)*
     *  已安装，则直接执行 `build-tpl`

> 通常，我们用配置文件指明「构建插件包」，也可以直接在命令里指明，比如 dcli build --builder=build-h5；后者往往适用于一套代码打包出多种结果，如京东的 Taro cli

平时大家用惯了 `npm run build` `yarn build`，只需在我们的模板中的 `package.json` 添加一行:

{
        "script": {
    ++      "build": "dcli build"
        }
    }
    复制代码

#### 5.6 **dev**命令：启动 devServer 进行调试 ####

类似 build 只不过 webpack 配置不同，此处略

### 6 模板插件包 ###

核心功能：提供模板文件夹 + 文件夹的拷贝。这里同样提供了一个样例工程 [gen-tpl][- 1] *(仅 50 行代码)*

处理流程如下：

1.  询问用户，并获取反馈的答案
    
     *  比如工程名是什么，描述一下你的工程，是否使用 TypeScript，是否使用 Sass/Less/Stylus 等
2.  根据用户的答案，拷贝对应的模板，细分两种拷贝
    
     *  直接拷贝，直接把模板插件包里的文件夹/文件，拷贝到用户工程目录
     *  填充模板拷贝，将用户答案，填充到文档的对应位置，类似 WebpackHTMLPlugin、ejs，如将 `name: <%= packageName %>` 填充成 `name: 我的工程`
3.  在工程中执行 npm 依赖的安装

![1 4][]

【重点来了】看似流程蛮多，其实只用一个现成的轮子即可搞定，即 [yeoman-generator][]，它帮我们把这些过程都封装好了，我们只需继承基类，并写几个预设的生命周期函数即可，无脑到令人发指 *(细节处理，可参考模板仓库)*

module.exports = class extends Generator {
      // 【问询环节】
      prompting() {
        return this.prompt([
          {
            type: 'input',
            name: 'appName',
            message: '请输入项目名称：',
          },
          {
            type: 'list',
            choices: ['Javascript', 'TypeScript'],
            name: 'language',
            message: '请选择项目语言',
            default: 'TypeScript',
          },
        ]).then(answers => {
          this.answers = answers
        })
      }

// 【模板拷贝】  
writing() \{  
// 从模板路径拷贝到工程路径  
this.fs.copy(this.templatePath(), this.destinationPath())  
\}

// 【安装依赖】  
install() \{  
this.installDependencies()  
\}

end() \{  
this.log(‘happy coding!’)  
\}  
\}  
复制代码

很明显，「模板插件包」导出的是一个 class，我们需要通过上文提到的「全局命令包」里的 `yeoman-environment` 来启动：

// 【节选自 全局命令包 init 命令，略修改以增加可读性】
    yoemanEnv.register(resolveFrom('./maoda', 'gen-tpl'), 'gen-tpl')
    yoemanEnv.run('gen-tpl', (e, d) => {
      d && this.console('happy coding', 'green')
    })
    复制代码

这里同样用到前文提到的 `resolve-from` 包，进行跨目录的引用解析

> yeoman 是一个比较完善的生态，模板插件包可用 yeoman 提供的全局命令 yo 来创建，但并非必要，此处就不展开说了

### 7 构建插件包 ###

> 同样我们提供了一个构建插件包的模板 [build-tpl][- 2] *(20行代码，启动 webpack)*，webpack 配置都是空的，大家在开发过程中可自行定制

构建插件包其实核心就是 webpack 能力，webpack 能力这里就不展开说了，这里只描述一下调用关系

以 `dcli build` 为例，「全局命令包」在收到 build 命令后，启动「构建插件包」

importFrom(process.cwd(), 'build-tpl')
    复制代码

没错，就是这么简单，[import-from][] 库能跨文件目录，指定使用特定目录的文件；使得**全局包可以直接去执行工程目录的包** 效果与同工程下 `require('build-tpl')` 一样

> 此处也可以使用 import-cwd 库

而 build-tpl 这个构建插件包，负责将内置的 webpack.config.js 与用户工程下自定义的 webpackCustom 进行 merge，然后执行 webpack 流程

![1 5][]

> 当然，构建工具不一定非要使用 webpack，比如可以选择 rollup 或者像 Taro 在构建小程序代码时候，自己创建一套工具

### 8 写在最后的话 ###

笔者认为，只有够精简，才能降低入门门槛，才能强化记忆；因此，本文的案例，在成熟的脚手架上进行不断删减，剔除掉哪些徒增记忆负担的部分，只保留精髓和核心，旨在快速在脑海里建模出一个企业级脚手架

同时提供了脚手架 3 个组成部分的 仓库/npm 包，以增加可操作性

如需引用与实际开发中，我们需要继续丰满其血肉，包括但不限于：

*  异常处理 (如一些边界情况)
 *  webpack 配置部分需完善 *(本 demo 中 webpack.config 是空的)*
 *  UI 和提升语可更友好
 *  根据业务需求，扩展额外的命令，比如卸载包，发布cdn等

文章博客地址：[github.com/imaoda/js-f…][Link 1] 欢迎批评指正

[Link 1]: https://github.com/imaoda/js-front-end-practice
[-]: https://github.com/imaoda/cli-tpl
[- 1]: https://github.com/imaoda/gen-tpl
[- 2]: https://github.com/imaoda/build-tpl
[Image 1]: 
[1]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02aab620e6?imageView2/0/w/1280/h/960/format/webp/ignore-error/1
[1 1]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02aecff64c?imageView2/0/w/1280/h/960/format/webp/ignore-error/1
[1 2]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02ab1e071a?imageView2/0/w/1280/h/960/format/webp/ignore-error/1
[1 3]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02aaca0ba4?imageView2/0/w/1280/h/960/format/webp/ignore-error/1
[1 4]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02ab070f47?imageView2/0/w/1280/h/960/format/webp/ignore-error/1
[yeoman-generator]: https://www.npmjs.com/package/yeoman-generator
[import-from]: https://www.npmjs.com/package/import-from
[1 5]: https://user-gold-cdn.xitu.io/2019/8/27/16cd2a02ee4ff6de?imageView2/0/w/1280/h/960/format/webp/ignore-error/1