vite+ts+vue结合eslint、prettier、husky、lint-staged、commitlint搭建开发环境
概述
最近在看公司项目里面的工程化配置的时候，看到了很多关于代码检测，ts类型约束，git提交检测，代码格式化等规范问题，关于一些工程化的工具，这里总结出来并实践体验配置的过程，包括配置的时候一些踩坑经验,加深对项目工程化的理解，后面如果能用到也有个参考。
第一步：利用vite搭建vue+ts项目
这里使用vite官方搭建Vite项目的指示，更多创建方式和模板可以前往官网查看。
后续包管理工具操作都使用yarn
//执行脚本
yarn create vite my-vue-app --template vue-ts
//进入到创建的项目执行
yarn
安装完成后项目结构如下：
修改tsconfig.json文件配置
修改大概两处，不然后面会报错
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
/* Bundler mode */
"moduleResolution": "node",//改为node
// "allowImportingTsExtensions": true,//注释
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "preserve",
/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
"references": [{ "path": "./tsconfig.node.json" }]
}
第二步：添加prettier
简介
简单来说prettier就是个代码格式化工具，可以帮助我们规范化代码，统一风格，多人协作开发必不可少的工具，当然可以选择其他代码格式话工具，看团队需求。
安装
//prettier
yarn add --dev --exact prettier
在项目根目录下新建.prettierrc文件，执行代码格式化命令的时候，内部会自动读取该文件中的配置信息，从而实现根据配置格式化，配置如下：
{
"tabWidth": 2,//缩进
"singleQuote": true//是否全部使用单引号
}
配置
根据团队需要，更多关于.prettierrc文件属性配置的风格可以参考prettier配置指南。
添加格式化项目代码的脚本命令，在package.json文件中script配置如下脚本：
"prettier:src": "prettier --write \"src/**/*.{ts,js,vue}\"",//表示格式化src文件下的ts,js,vue结尾的文件
"prettier": "prettier --write .",//格式话当前项目所有文件（不推荐使用，项目大就很卡)
测试
接下来可以使用npm run prettier:src,可以新建js文件，格式故意打乱，看对应文件下的文件是否被插件格式化成功，出现以下输出表示执行成功。
然后记得把vscode中的Prettier - Code formatter插件装上，这样我们在写代码的时候就可以使用快捷键Ctrl+Shift+F格式了。
第三步：添加eslint
简介
多人协作开发，不仅仅在格式上面，还需要在代码上能反馈出错误问题，ESLint 静态地分析你的代码以快速发现问题。它内置于大多数文本编辑器中，但你也可以在持续集成管道中运行 ESLint。
安装
yarn add --dev --exact eslint
初始化eslint配置
为了能让eslint文件能够识别和解析ts文件和vue文件，接下来初始化eslint+ts+vue的配置信息：
npx eslint --init
对应初始化的选项选择如下：
- How would you like to use ESLint?
- To check syntax, find problems, and enforce code style
- What type of modules does your project use?
- JavaScript modules (import/export)
- Which framework does your project use?
- Vue.js
- Does your project use TypeScript?
- YES
- Where does your code run?
- Browser、Node都选上
- How would you like to define a style for your project?
- Answer questions about your style
- What format do you want your config file to be in?
- JSON
- What style of indentation do you use?
- Tabs
- What quotes do you use for strings?
- double
- What line endings do you use?
- Windows
- Do you require semicolons? - No
- Would you like to install them now?
- YES
- Which package manager do you want to use? . - yarn
等待安装完成.....
途中顺便安装下vscode Eslint插件
eslint配置文件
安装完成过后，可以看到文件加根目录生成了一个.eslintrc.json文件：
{
"env": {
"browser": true,
"es2021": true,
"node": true
},
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:vue/vue3-essential",
],
"parserOptions": {
"ecmaVersion": "latest",
"parser": "@typescript-eslint/parser",
"sourceType": "module"
},
"plugins": [
"@typescript-eslint",
"vue"
],
"rules": {
//根据需要选择保留或者追加
// "linebreak-style": [
// "error",
// "windows"
// ],
// "quotes": [
// "error",
// "single"
// ],
// "semi": [
// "error",
// "always"
// ]
}
}
解决部分ESLint和Prettier冲突
根据eslint官方所说：如果你用的是ESLint，需要安装ESLint -config-Prettier，让ESLint和Prettier和睦相处。它关闭所有不必要的或可能与Prettier冲突的ESLint规则。
yarn add --dev --exact eslint-config-prettier
成功之后，.eslintrc.json的extend字段追加prettier,记住一定要加在最后，最终.eslintrc.json文件如下：
{
"env": {
"browser": true,
"es2021": true,
"node": true
},
"extends": [
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:vue/vue3-essential",
"prettier",//这是新加的一定要在最后
],
"parserOptions": {
"ecmaVersion": "latest",
"parser": "@typescript-eslint/parser",
"sourceType": "module"
},
"plugins": [
"@typescript-eslint",
"vue"
],
"rules": {
"array-callback-return":"error"
}
}
测试
安装成功之后，写个demon来测试下Eslint是否能检测文件的错误信息。
新建src/utils/couter.js:
export function sum(num1: number, num2: number) {
return num1 + num2;
}
const list = [1, 2, 3].map((item) => {
console.log(item);
});
修改App.vue
<template>
<div>
{{ userInfo.name }}
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const age = 12;
const userInfo = ref({
name: '小明',
sex: 12,
});
</script>
package.json新增以下脚本：
"eslint": "eslint \"src/**/*.{ts,js,vue}\" \"src/main.ts\""
执行npm run eslint,出现以下信息则代表可以校验ts文件和vue组件校验成功：
第四步：添加husky
简介
在介绍 husky 之前，首先要理解什么是 hook（钩子），在前端 Vue 框架中提供了 beforCreated、created、beforeMounted、mounted 等函数、这些函数都是钩子，也常被称为‘生命周期钩子函数,它们会在 Vue 实例化过程中有序地执行。
在 Git 中也存在一些钩子，其中较常用的有 pre-push、pre-commit、commit-msg ，其中 pre-commit 钩子会在 commit 前触发，pre-push 会在 push 前触发，commit-msg会在git commit触发（提示：所有钩子默认情况下是禁用的） 我们这里用到的主要是pre-commit、commit msg钩子。
安装
//安装prettier
yarn add --dev --exact husky
添加一个script脚本到package.json
npm pkg set scripts.prepare="husky install"
此时会看到package.json自动生成了：
生成.husky文件
npm run prepare
配置
npx husky add .husky/pre-commit
npx husky add .husky/commit-msg
此时生成了如下两个钩子文件：
使用husky的pre-commit钩子：
需求：git commit之前的时候，我们将src文件夹下的以js、ts、vue结尾的文件进行eslint检测，不合法则放弃暂存。
.husky/pre-commit文件配置如下：
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run eslint//git commit之前，会执行这个脚本，错误则不会暂存，成功则会暂存
此时git log日志输出如下表示文件eslint校验失败，则不会commit：
然后我们将对应文件修改后，然后再次提交，此时没有报错，说明git提交代码之前校验成功：
使用husky的commit-msg钩子：
这个钩子会在 git commit -m "xxx"的时候出发，此时我们可以做提交信息校验的工作，如果没有提交信息的规范，多人开发的时候，提交信息就会显得杂乱无章，五花八门，因此，我们给提交信息规范化后，例如：
git commit -m <type>[optional scope]: <description> // 注意冒号后面有空格
- type：提交的类型（如新增、修改、更新等）
- optional scope：涉及的模块，可选
- description：任务描述
示例：feat: 新增了一个搜索功能在首页。
这样规范后，我们就可以很清晰看到本次提交是做了哪些修改，方便后期的查阅和维护。
type 类型
常见的如下
| 类别 | 含义 |
|---|---|
| feat | 新功能 |
| fix | 修复 bug |
| style | 样式修改（UI校验） |
| docs | 文档更新 |
| refactor | 重构代码(既没有新增功能，也没有修复 bug) |
| perf | 优化相关，比如提升性能、体验 |
| test | 增加测试，包括单元测试、集成测试等 |
| build | 构建系统或外部依赖项的更改 |
| revert | 回退某个 commit 提交 |
第五步：添加校验工具commitlint
要对上面的git提交信息进行规范校验，并且在不合规的情况下抛出错误，我们就需要用到commitlint:
安装@commitlint/cli 和@commitlint/config-conventional
yarn add --dev --exact @commitlint/cli @commitlint/config-conventional
生成.commitlintrc.json文件
echo {"extends": ["@commitlint/config-conventional"] } > .commitlintrc.json
此时根目录生成了commitlint的配置文件.commitlintrc.json:
配置
其实就这样就可以了，然后可以根据需要，更改一些默认配置，以下为示例:
{
"extends": ["@commitlint/config-conventional"],
//提交类型，不满足直接回抛错
"type-enum": [
2,
"always",
["feat", "fix", "docs", "style", "refactor", "test", "chore", "revert"]
],
}
修改./husky/commit-msg钩子文件：
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
# 新增
npx --no -- commitlint --edit ${1}
测试
更改文件，然后信息输入为修改配置文件,会发现提交失败：
修改提交信息为：feat: 修改配置文件，成功了！！，记住feat冒号后面一定要有一个空格，这算是一个坑吧。
上面会先经过pre-commit钩子执行eslint代码校验，然后经过commit-msg钩子校验提交信息合法后才提交到本地仓库。
第六步：添加lint-staged
问题：
当我们使用eslint校验代码或者prettier格式化代码的时候，会将本地的所有代码进行检测和格式化，我们期望的是：使用eslint和prettier工具的时候，只对我当前修改过的文件进行检验和处理，其他的文件我没改动，肯定不需要额外的处理，这样的话，会提升我们的开发效率，处于这个考虑，lint-staged是一个只对将要通过git提交的文件（staged），执行自定义脚本的工具。
安装lint-staged
yarn add --dev --exact lint-staged
添加lint-staged配置到package.json中
"lint-staged": {
//本地暂存库需要commit的文件才会执行以下对应脚本,eslint和prettier需要的路径会后面自动追加检测
"*.{ts,js,jsx,vue}": [
"eslint",
"prettier --write"
]
}
需求
需求：eslint校验改动的代码，然后自动格式化格式不匹配的代码。
App.vue
<template>
<div>
{{ userInfo.name }}
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const userInfo = ref({
name: '小明',
sex: 12,
});
//打乱格式
const res = [1,2,3].map(item=>{
//这里没有返回值，eslint会报错
console.log(item)
})
</script>
main.ts
import { createApp } from 'vue';
import './style.css';
import App from './App.vue';
import { sum } from './utils/counter';
createApp(App).mount('#app');
//格式错误
console.log(sum());
//不能使用var
var age = 123;
以上代码我们在执行git commit -m "feat: 修改app组件和main.ts文件"命令后会报错如下：
将代码修改成正确的之后执行，会发现提交成功，顺便还把格式错误的文件给自动格式化了然后提交了。
处理vite+ts搭建的部分报错处理
在模板中使用script脚本中的数据，会发现模板直接报错，官方推荐的volar安装了都没用，报错如下：
处理办法：
根据官方提供的方法，开启Volar Takeover 模式，然后重启编辑器就没有报错了。