版权声明：本人文章仅在掘金平台发布，请勿抄袭搬运，转载请注明作者及原文链接。

网页版带有主题和代码高亮，阅读体验更佳~

刚学习 Vue、React 的时候，还只会使用 cli 创建项目。Vue 内置的 ESlint 工具最令人头疼，常常报错导致项目跑不起来，最后只能删除项目重新创建。上一家公司也是，都是水平很差的前端，项目根本不敢开 ESlint，没有人能解决 ESlint 的报错问题，导致项目代码里充斥着各种奇珍异兽。这些东西如果不熟悉，不理解，遇到问题很难去解决，而此类工程化相关的东西，我觉得是 3 到 5 年前端能和别人最快拉开差距的知识点。抛开 JS、框架，我们每天打交道最多的就是这些东西，一个优秀的前端项目工程，代码提交检查、代码格式规范是基本配置，在此基础上才能去谈 TS、CI CD、单元测试等内容。

本篇文章就围绕这些工程化工具为大家做一次入门引领，从 0 到 1 搭建一个开源项目，从整体的视角来看待这些工具，从而更好地掌握工具，而不是排斥工具、害怕工具。

阅读本篇文章，你将学到以下工具的使用：

工具	描述
`ESlint`	代码格式校验
`husky`	执行 `git` 钩子函数，一般用来检查 `commit` 信息
`lint-staged`	与 `husky` 配套使用，只检查暂存区的代码
`conventional-changelog-cli`	生成 CHANGELOG.md 文件，记录库的版本日志
`LICENSE`	如何选择开源协议及如何快速生成开源协议
`.editorconfig`	编辑器配置
`bumpp`	自动升级版本而不用每次都手动改
`package.json`	依赖配置文件，一些你在平时项目不会用也不会关注的字段
`vite`	如何构建一个 npm 包

从开源项目中学习

随便打开一个开源项目的 github 仓库，就会发现除了核心代码之外，还有很多工程化相关的配置文件：

.husky
.eslintrc
.eslintignore
.editorconfig
.npmrc
.stylelint.js
.commitlint.config.js
README.md
LICENSE
CHANGELOG.md

除此之外，还有一个最关键的文件：package.json，这是最关键的一员，我们会在具体的知识点中来讲解这个文件。

ant-design 的部分工程配置文件

基于 vite 搭建项目

出于方便高效等各种原因选择 Vite，但是这不是最关键的内容，你也可以使用 Webpack。为了保持学习的一致性，建议你和我保持一样的操作。

使用 Vite，对 Node 版本有一定要求，你可以选择和我保持同样的版本：

Vite 需要 Node.js 版本 14.18+，16+。然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。

包管理工具我选择 yarn，你也可以选择 pnpm。

在终端执行命令创建项目：yarn create vite，我们这里并不依赖任何框架，上下箭头移动选择 others，然后回车：

它又会问我们是不是 Electron 项目，当然也不是，选择第一个回车：

接下来它会询问我们选择一个预设，这里我们选择库模式：

它还会问我们是否需要 Typescript，我们这里需要：

Vite 为我们生成的项目模板：

可以看到它自带了一个 lib 文件，这其实就是我们最终生成的库的源码包，但是现在还只是个初级版，还不符合我们的需求。接下来我们需要做一些额外的配置。

编写 vite.config.js

首先明确我们需要支持的模块化，如果需要同时支持 esm 和 cjs，那么我们可以生成两个最终产物，分别定义两种模块化的入口，如果你只支持 esm 或者 cjs 那么只生成一个最终产物就可以了，当然你还可以使用 UMD，一个最终产物同时支持以上两种模块化。这里我们以同时生成 esm 和 cjs 两种包为例编写配置文件。

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    target: 'modules', // 详情参考官方文档：https://cn.vitejs.dev/config/build-options.html#build-target
    minify: true, // 是否开启代码压缩
    rollupOptions: {
      input: ['src/index.ts'], // 打包的入口文件 https://cn.rollupjs.org/configuration-options/#input
      output: [ // 产物输出配置
        {
          format: 'es', // 指定模块化类型 https://cn.rollupjs.org/configuration-options/#output-format
          entryFileNames: '[name].js', // 入口文件名，默认 https://cn.rollupjs.org/configuration-options/#output-entryfilenames
          preserveModules: true, // 该选项将使用原始模块名作为文件名
          dir: 'es', // 输出的目录
          preserveModulesRoot: 'src' // 确保输出的目录和输入时的一致
        },
        {
          format: 'cjs', // 指定模块化类型
          entryFileNames: '[name].js',
          preserveModules: true,
          dir: 'lib',
          preserveModulesRoot: 'src'
        }
      ]
    },
    lib: { // https://cn.vitejs.dev/config/build-options.html#build-lib
      entry: './index.ts', // 定义作为库的入口是哪个
    }
  },
});

我们执行下 yarn build 来看看当前配置会为我们生成什么样的产物：

来看个小插曲，因为我们 Vite 生成的模板 src 下的入口默认是 main.ts，但是我们在配置文件写的是 index.ts，它找不到 index.ts 文件就报错了：

首先需要将 main.ts 改名为 index.ts，然后需要改写里面的代码，我们随意写个变量并导出，因为我们是库，如果不导出模块是会报错的。

来看看最终打包的产物：一个 es 一个 lib，这里有了这两个文件后，我们接下来可以做的事就多了。

针对 es 和 lib 做处理

第一件事，这两个包我不希望他们被提交到仓库里，我需要在 .gitignore 文件里忽略它们：

...

es
lib

...

第二件事，这两个包必须得在 package.json 里定义它的入口文件，否则发布成 npm 库后，别人下载下来找不到入口文件，也就没法引用代码了。

{
  "name": "vite-project",
  "private": false,
  "version": "0.0.0",
  "type": "module",
  "main": "lib/index.js",
  "module": "es/index.js",
  "types": "./index.d.ts",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  },
  "files": [
    "es",
    "lib",
    "index.d.ts"
  ],
  "devDependencies": {
    "typescript": "^4.9.4",
    "vite": "^4.0.4"
  }
}

main 字段我们定义 cjs 模块的入口，module 我们定义 es 模块的入口。另外，private 设置为 false，files 是指我们最终发布 npm 时要上传的文件，现在我们需要将 es 与 lib 两个文件加进来，这样我们发布代码时才能将代码发布上去，不然别人下载你的包会连代码都没有，这里一定小心，非常重要！

配置 ESlint

第一步，在终端执行命令：npx eslint --init，它会让我们选择模式：

仅仅检查语法
检查语法，发现问题
检查语法，发现问题，强制代码风格

这里我们选择第二个。

接下来它会询问我们使用的模块化，我们选择 esm：

它会问我们的项目是否基于某一个框架，由于我们这里没有，就不选，你可以根据你自己的情况选择：

接下来的就不是很重要了，我的选择给大家一个参考：

最终生成一个 .eslintrc.cjs 的规则配置文件，但是它会报红。因为我们是使用的 esm，我们把后缀 cjs 换成 js 就行了。不过这样其实也不太好，因为模块化可能会有各种潜在问题，所以我们直接将文件格式改成 json，也是一样的。这里顺嘴提一句，当项目存在多个 .eslintrc 配置文件且后缀不同时，优先级是 js > json > yaml，没有后缀的话默认是 json 格式。

{
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "overrides": [
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": [
    "@typescript-eslint"
  ],
  "rules": {
    "semi": 2
  }
}

我们可以在 rules 字段下新增一个规则 "semi": 2，检查下 index.ts 中有没有报红，报红就说明配置生效了。其中，0 是关闭，1 是警告，2 是报错，还有其它的一些规则值，大家感兴趣可以自行研究，我们这里使用 012 已经够用了。

接下来简单讲讲配置中各个主配置字段的含义：

eslintrc 配置字段含义解读

字段	描述
`env`	在配置文件中使用 `env` 键指定环境，并通过将每个环境设置为 `true` 来启用想要的环境
`globals`	要在配置文件中配置全局变量，请将 `globals` 配置属性设置成对象，其中包含为你要使用的每个全局变量命名的键。对于每个全局变量的键，将相应的值设置为 `writable` 以允许变量被覆盖，或者 `readonly` 以禁止覆盖。比如你可以把 `window` 禁用了，设置为只读
`extends`	`eslint` 检查用哪些规范，包括内置的和第三方的
`overrides`	覆盖配置中基于文件 `glob` 模式的设置 (你只要知道基本用不到就对了)
`parser`	配置解析器
`parserOptions`	`ESLint` 允许你指定你想要支持的 `JavaScript` 语言选项。默认情况下，`ESLint` 希望使用 `ECMAScript 5` 语法。你可以通过使用解析器选项来覆盖这一设置，以实现对其他 `ECMAScript` 版本以及 `JSX` 的支持。
`plugins`	对于特殊语法需要使用插件进行识别，例如对 `TS`、`React` 语法的检查都依赖插件
`rules`	具体的校验规则，比如有分号没分号，允不允许 `console.log` 等

到这里我们的 eslint 基本就配置完了，其实很简单对不对？但是我们看到 .eslintrc 的缩进是 4 个，我个人是不喜欢 4 缩进的，这里就引出了另一个配置文件：.editorconfig。

不过在讲 .editorconfig 之前，还有一个文件和 ESlint 有关，那就是 .eslinignore。并不是所有文件都需要代码检查，ESlint 一般也只辅助我们检查 js、ts 代码，所以有些文件我们得忽略掉。在根目录下创建文件：.eslintignore：

一些构建后的产物没有检查的意义，所以有必要忽略掉。目前我们需要忽略的文件就是 node_modules、test、dist、build、es、lib。你若有其它的可忽略文件加进来即可。

.editorconfig

这个文件有什么意义？

.editorconfig 有助于为跨不同编辑器和 ide 从事同一项目的多个开发人员维护一致的编码风格。.editorconfig 项目由用于定义编码样式的文件格式和一组文本编辑器插件组成，这些插件使编辑器能够读取文件格式并遵循已定义的样式。.editorconfig 文件很容易阅读，并且可以很好地与版本控制系统配合使用。

假如你用 macOS 开发，我用 windows 开发，那么两个系统使用的编码格式不同，就会出现乱码，你一定遇到过下载的代码在换行时有一个 DR 符号的情况，这就是系统差异导致的。还有就是，有的人喜欢 4 个缩进，有的喜欢 2 个，缩进不同就会导致代码差异比较大，有些人还比较喜欢使用代码格式化工具，一保存就会自动格式化，导致代码一堆冲突，这时候解决起来就麻烦了。

.editorconfig 长什么样呢？一般是在项目的根目录下新建一个 .editorconfig，不带任何后缀即可，它会被编辑器自动解析。

贴一下我的配置：

# Editor configuration, see http://editorconfig.org
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
max_line-length = off
trim_trailing_whitespace = false

我这里将代码缩进设置为 2 个，刚才的 .eslintrc 立马有了反应，缩进线变了，可以进行 2 个空格的缩进了：

这就是 .editorconfig 的能力，可以控制编辑器的缩进、utf 编码、去除空白符等等。这对团队协作非常重要，有利于大家的项目保持统一的风格，避免一些非代码问题导致的问题降低开发效率。

husky & lint-staged 代码检查并修复

团队协作最重要的就是标准和规范，没有标准规范就会有各种各样的问题，例如代码格式混乱、commit 信息千奇百怪。标准规范制定虽然容易，执行落地却很困难，所以必须借助于工具。ESlint 虽然已经帮助我们避免大量的代码格式问题了，但是人总是会出错的，为了错误代码不被提交，特别是有些人使用未定义的变量，这样一定会导致代码报错，从而导致生产故障，这时就需要其它工具来进行辅助检查。

husky 加上 lint-staged 就是这种帮助代码检查的工具，配合 ESlint 一起使用。

暂存区代码 commit 前进行修复

第一步，执行 yarn add husky lint-staged -D，先下载依赖。

第二步，执行 npx husky-init && husky install。该命令会在 package.json 中新增一个 script："prepare": "husky install"。

"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "prepare": "husky install"
},

紧接着会下载 .husky 文件，也就是 git hooks，这些钩子会在一定的时机执行。husky 的 hooks 有 pre-commit、commit-msg、pre-push 等。同时，它会生成一个 pre-commit 的 shell 脚本文件，负责执行 pre-commit 钩子。这个脚本文件就是在里面输入 shell 命令，husky 会在一定的 git 执行时机执行这个命令。你可以理解为类似于在终端执行的命令，只不过写在了这个文件里而已。

pre-commit 钩子是在 git commit 之前执行，我们现在要做的就是利用这个钩子在代码 commit 前修复一些错误。

第三步，package.json 新增 lint-staged 配置，这里的意思是在每次 commit 执行之前也就是 pre-commit 的时候执行 lint-staged 命令。它会匹配以 .js、.ts 结尾的文件，并修复这些文件里的代码格式错误，并继续将修改后的文件存入暂存区，pre-commit 之后才会执行我们提交的 commit 命令。

"lint-staged": {
  "src/**/*.{js,ts}": [
    "eslint --fix",
    "git add"
  ]
},

第四步，我们需要将 pre-commit 文件里的 npm test 替换为 npx lint-staged，这样它就会在 pre-commit 钩子执行时调用第三步里的方法，对暂存区的代码进行扫描和修复。

我们来测试一下，src/index.ts 里我们之前留了几个分号的报错，现在我们将它进行 commit：

可以看到分号的错误已经被修复。

对 commit 信息进行格式检查

如果你接触过一些正式的 commit 规范，会知道我们的 commit 信息一般是这样：feat: 搭建项目骨架。首先是此次变更的关键词，常见的有 feat、style、docs、chore 等。具体看下表：

关键字	具体含义
`feat`	新增特性 (feature)
`fix`	修复 bug(bug fix)
`docs`	修改文档 (document)
`style`	代码格式修改
`refactor`	代码重构 (refactor)
`perf`	改善性能 (performance)
`test`	测试
`build`	变更项目构建或外部依赖
`chore`	杂项
`revert`	代码回退

这样的信息我们也有工具进行规范。我相信有人看到这里会觉得这种东西似乎没有什么作用，有点多此一举了。仁者见仁智者见智吧，我觉得专业的前端团队这种东西应该都会做，毕竟工程化的东西，其它的都能做，这件小事也就是顺手的事情，有利无弊的事，做了总比没做好。

第一步，下载两个依赖：yarn add @commitlint/cli @commitlint/config-conventional -D。

第二步，终端执行命令：npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"，它会在 .husky 下生成一个 commit-msg 的 shell 脚本文件，并且会在我们 commit 提交 message 时执行 npx --no-install commitlint --edit 命令，对我们的信息进行校验。

但是怎么个校验法它并不知道，所以需要我们在根目录下编写一个配置文件 commitlint.config.js：

const types = ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'release', 'chore', 'revert'];

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-empty': [2, 'never'],
    'type-enum': [2, 'always', types],
    'scope-case': [0, 'always'],
    'subject-empty': [2, 'never'],
    'subject-case': [0, 'never'],
    'header-max-length': [2, 'always', 88],
  },
};

以上配置仅供参考。来测试下：

一个小插曲，报错的信息说不支持 esm，需要导出 cjs 模块。那么我们需要将 commitlint.config.js 替换为 commitlint.config.cjs，并将其进行 module.exports。

继续测试，可以看到配置已经生效了。

不过有时候不想这个配置生效，觉得这个校验很麻烦怎么办？就比如前同事留下的垃圾代码，每次 commit 触发校验一堆报错，老代码又不想动，新代码又必须提交，怎么办？其实加个参数就可以了：--no-verify。例如：git commit -m 'feat: 完成项目骨架' --no-verify，它就会跳过 commit 校验，包括代码格式校验及 commit message 校验。

生成 CHANGELOG.md 更新日志

打开一些开源项目的 github 仓库，发现人家对每次版本更新都有很详细的记录，有时候觉得人家真细致，不愧是开源作者，但其实人家也是借助的工具。

第一步，执行命令：yarn add conventional-changelog-cli -D。

第二步，在 package.json 中配置脚本："changelog": "conventional-changelog -p -i CHANGELOG.md -s"。

我们来测试下：yarn changelog。

就这样两步就能生成 CHANGELOG.md。

自动升级版本号

每次发布新的版本都要手动更改 package.json 的 version 实在是麻烦，而且最麻烦的是会忘记更改。可以下载 yarn add bumpp -D，每次 release 之前都执行下 bumpp，它会提示我们对版本进行升级，还有各种合适的版本号推荐，例如 beta 版、major 版等。

在 package.json 中新增一个 script："version": "bumpp"。终端执行 yarn version 看看效果：

它会继续问我们是否需要更改到其它版本，我们这里不需要，直接选择 as-is 0.0.2：

最后它会问我们是否需要继续，我们选择 N：

主要的功能是防止忘记更改版本，可以将其放到每次发布之前执行。

快速生产开源协议

开源项目离不开开源协议，但是不可能手写开源协议吧？其实这个也不用我们自己操作，vscode 有插件帮助我们快捷生成。

快捷键 shift command (ctrl) p 可进行选择：

开源协议有很多，这里就不展开了，一般选择 MIT 就可以。下面列个常见开源协议的资料，有兴趣的话可以细看。

协议名称	协议描述
`BSD` （Berkeley Software Distribution license）	`BSD` 允许使用者修改和重新发布代码，也允许基于 `BSD` 代码上开发商业软件的发布和销售。遵循 `BSD` 协议的代码完全可控，必要的时候可以修改或者二次开发
`MIT`（Massachusetts Institute of Technology）	`MIT` 是宽松的许可协议，作者只想保留版权，而无任何其它限制。只需在发布的源代码、二进制可执行文件相关文档中包含 `MIT` 许可协议声明，便可自由的使用、修改源代码、作为商业软件再发布、甚至使用开源机构名字做产品的市场推广
`Apache Licence 2.0`	详见：开源协议详解
`GPL`（General Public License）	代码的开源免费使用和引用，修改及衍生代码的开源免费使用，但其不允许修改后和衍生的代码做为闭源的商业软件发布和销售（只要使用 `GPL` 协议的相关类库与代码，则该软件亦必须采用`GPL` 协议，必须开源与免费）
`LGPL`（Lesser General Public License）	`LGPL` 允许商业软件通过类库引用方式使用 `LGPL` 类库而不需要开源商业软件的代码，如果修改了 `LGPL` 协议的代码或衍生，则所有修改的代码和衍生的代码都必须采用 `LGPL` 协议
`Mozilla`（Mozilla Public License）	在自己已有的源代码库上加一个接口，除了对接 Mozilla Public License 开源库的接口程序源代码以MPL许可的形式对外许可外，源代码中的其他源码可以不用 `MPL` 许可证的方式强制对外许可

完善 package.json 配置

配置完开源协议文件后，还需要在 package.json 里新增字段："license": "MIT"。

除此之外，还可以设置关键词，简要标记下库的功能和技术点：

"keywords": [
  "vite",
  "commitlint",
  "husky",
  "CHANGELOG",
  "LICENSE",
  "ESlint"
],

files 字段再把 README 和 LICENSE 带上，因为使用了 TS，index.d.ts 也是必须上传的。另外，上传哪个类型声明文件，是因为我们配置了字段："types": "./index.d.ts",。这里配置的是谁，你在 files 字段里上传的类型声明文件就是谁。

"files": [
  "es",
  "lib",
  "README",
  "LICENSE",
  "index.d.ts"
],

还有 repository 和 publishConfig，分别记录库的代码仓库及发布时 npm 的镜像地址。如果是开源的话就是 https://registry.npmjs.org/，不是开源的话可以设置成自己或者公司的私有镜像地址。

"repository": {
  "type": "git",
  "url": "https://github.com"
},
"publishConfig": {
  "registry": "https://registry.npmjs.org/"
}

贴一下完整的 package.json：

{
  "name": "open-source-config-template",
  "private": false,
  "version": "0.0.1",
  "type": "module",
  "main": "lib/index.js",
  "module": "es/index.js",
  "types": "./index.d.ts",
  "license": "MIT",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext '.js,.ts' --fix",
    "prepare": "husky install",
    "commit": "git-cz",
    "version": "bumpp",
    "changelog": "conventional-changelog -p -i CHANGELOG.md -s",
    "before-release": "yarn changelog && yarn build && bumpp"
  },
  "lint-staged": {
    "src/**/*.{js,ts}": [
      "eslint --fix",
      "git add"
    ]
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  },
  "files": [
    "es",
    "lib",
    "README",
    "LICENSE",
    "index.d.ts"
  ],
  "keywords": [
    "vite",
    "commitlint",
    "husky",
    "CHANGELOG",
    "LICENSE",
    "ESlint"
  ],
  "devDependencies": {
    "@commitlint/cli": "^17.6.5",
    "@commitlint/config-conventional": "^17.6.5",
    "@typescript-eslint/eslint-plugin": "^5.59.8",
    "@typescript-eslint/parser": "^5.59.8",
    "bumpp": "^9.1.0",
    "commitizen": "^4.3.0",
    "conventional-changelog-cli": "^2.2.2",
    "eslint": "^8.42.0",
    "husky": "^8.0.0",
    "lint-staged": "^13.2.2",
    "typescript": "^4.9.4",
    "vite": "^4.0.4"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com"
  },
  "publishConfig": {
    "registry": "https://registry.npmjs.org/"
  }
}