提示

  如果团队开发间使用的都是 vscode 的话,我们是可以通过插件实现配置同步的。

  其实,通过下面的学习我们可以发现,像 Prettier 格式化、ESLint 检测/修正在开发阶段都是优先使用 vscode 插件来自动化完成的(方便、快捷)。

  而项目中安装 Prettier、ESLint 的 npm 包,往往是用来制定格式化(.prettierrc)、检查(.eslintrc.js)的主体方向的,可以为当前项目进行提供定制化的代码风格

  上述的开发模式可以让开发变得更加快捷、方便。

团队开发 个人开发
EditorConfig EditorConfig
Prettier Prettier
ESLint ESLint
Git 钩子
Commit 规范

# 一、EditorConfig 工具

  -EditorConfig (opens new window) 有助于为不同 IDE 编辑器上处理同一项目的多个开发人员维护一致的编码风格

比如:有的人使用的是 VSCode、有的人使用的是 Webstorm 等

# 1、安装插件

  首先,我们得在编辑器中安装 EditorConfig 提供的插件,插件地址:

https://editorconfig.org/#download

# 2、.editorconfig

  然后,就可以在项目根目录创建.editorconfig 文件并进行编写。下面我们以 vue 中的.editorconfig 文件为例:

.editorconfig 文件在很多开源项目中都可以看到它的影子,如:vue2 (opens new window)react (opens new window)

提示

  现在 EditorConfig 中的许多配置,在 Prettier/ESLint 中也可以进行配置了。如果团队开发中使用的是同一种 IDE,不使用 EditorConfig 也是可以的。

root = true

[*] # 表示所有文件适用
charset = utf-8 # 设置文件字符集为 utf-8
indent_style = space # 缩进风格(tab | space)
indent_size = 2 # 缩进大小
end_of_line = lf # 控制换行类型(lf | cr | crlf)
trim_trailing_whitespace = true # 去除行尾的任意空白字符
insert_final_newline = true # 始终在文件末尾插入一个新行

[*.md] # 表示仅 md 文件适用以下规则
max_line_length = off
trim_trailing_whitespace = false

# 二、Prettier 格式化

  -Prettier (opens new window) 是一款强大的代码格式化工具,支持 JavaScript、TypeScript、CSS、SCSS、Less、JSX、Angular、Vue、GraphQL、JSON、Markdown 等语言,基本上前端能用到的文件格式它都可以搞定,是当下最流行的代码格式化工具。

# 1、安装引入

npm install prettier -D
  • .prettierrc

官方配置说明:Options (opens new window)

{
  "useTabs": false, // 使用tab缩进还是空格缩进
  "tabWidth": 2, // tab是空格的情况下,是几个空格

  "trailingComma": "none", // 在多行输入的尾逗号是否添加(默认为all)
  "semi": false, // 语句末尾是否要加分号(默认为true)
  "singleQuote": true, // 使用单引号还是双引号(默认为false)
  "printWidth": 100 // 当行字符的长度(默认80)
}
  • .prettierignore
/dist/*
.local
.output.js
/node_modules/**

**/*.svg
**/*.sh

/public/*

# 2、格式化代码

# ① 手动

  使用 NPM 脚本格式化

npm run prettier

// package.json
{
  "scripts": {
    "format": "prettier --write src/"
    // "format": "prettier --write \"./**/*.{js,md,yml,ts,tsx}\""
    // "format": "prettier --write --parser typescript \"(src|test|packages|types)/**/*.ts\""
  }
}

# ② 自动

  使用 Prettier 插件格式化

Ctrl + S 保存

提示

  使用 vscode 的 Prettier 插件辅助我们进行格式化,对应开发个人项目非常有用,因为 ESLint 和 Prettier 规范都是自己制定的。

  但如果是拉取他人的项目(使用了 eslint/prettier)时,使不使用 Prettier 插件就有待考量了 🤔。

拉取的 eslint/prettier 项目处理

  对拉取的项目,我们可以根据不同的使用目的进行不同的处理:

  • 为他人项目做贡献 或者 仅仅是想学习一下源码

停用 Prettier 插件,格式化采用手动的 NPM 脚本格式化方式

  • 进行项目的二次开发

可以使用 Prettier 插件辅助开发,ESlint、Prettier 配置随便你怎么折腾!!

  • settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

# 三、ESLint 检测

  谈到 ESLint,就不得不提一下 typescript 的初次使用了,那个红色下划线亮得 😂

# 1、安装引入

  现在的 eslint 安装非常智能了,它可以根据你的选择自动安装相应的 npm 包。

当然,我们使用的如果是 vue-cli 等脚手架的话,也会根据我们的选择自动安装配置

npm init @eslint/config
√ How would you like to use ESLint? · problems
√ What type of modules does your project use? · esm
√ Which framework does your project use? · vue
√ Does your project use TypeScript? · No / Yes
√ Where does your code run? · browser
√ What format do you want your config file to be in? · JavaScript
√ Would you like to install them now? · No / Yes
√ Which package manager do you want to use? · npm

# 2、狭路相逢 ✨

  -ESLint (opens new window) 是用于对代码格式化进行检测的工具,默认有自己的代码规范;所以,首要解决的就是 ESLint 检测 和 Prettier 规范 的爱恨情仇,这样才能保证 Prettier 插件格式化的正常运行。

解决办法:让 ESLint 也去读取 Prettier 的风格

  • 安装
# 这俩在脚手架中可能已经集成了(例如:"@vue/eslint-config-prettier")
npm install eslint-config-prettier -D
npm install eslint-plugin-prettier -D
  • 配置
// .eslintrc.js

module.exports = {
  extends: [
    // 放在最后
    'plugin:prettier/recommended'
  ]
}

# 3、代码检测

# ① 手动

  使用 NPM 脚本格式化

npm run lint (在后面的 Git 钩子、Commit 规范中有应用场景)

// package.json
{
  "scripts": {
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
  }
}

# ② 自动

  使用 ESLint 插件检测/修复

  • setting.json

ESLint 插件配置:Settings Options (opens new window)

一般情况下我们是不会是使用 eslint 来作为默认的格式化程序的 eslint.format.enable

{
  "eslint.lintTask.enable": true,
  "eslint.validate": ["javascript", "javascriptreact", "vue", "typescript", "typescriptreact"],

  // 如果您使用 ESLint 作为默认格式化程序,则应在打开 editor.codeActionsOnSave 时关闭 editor.formatOnSave 。否则,您的文件将被修复两次,这是不必要的。
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

# 4、ESLint 配置

  如果我们在项目开发中,对 Vue、Eslint 等脚手架创建的项目中的某些规范不满意或者不想使用时,我们可以通过配置解决:

官方配置说明:Configure ESLint (opens new window)

"off" 或 0 关闭规则
"warn" 或 1 开启规则 使用警告级别的错误:warn (不会导致程序退出)
"error" 或 2 开启规则 使用错误级别的错误:error (当被触发的时候,程序会退出)

ESLint 配置文件中主要有 root (opens new window)env/globals/parserOptions (opens new window)plugins/extends (opens new window)rules (opens new window)

// .eslintrc.js

module.exports = {
  rules: [
    // 不要使用某个检查规则
    '@typescript-eslint/no-unused-vars': 'off'
  ]
}

# 四、Git 钩子

# 1、Husky 工具

  -Husky (opens new window) 是一个用于 Git 仓库的钩子(hook)管理工具,它能够帮助您在 Git 操作的不同阶段(pre-commit、commit-msg、pre-push)自动运行脚本,从而实现代码质量控制、预防错误和规范开发流程。

提示

  Husky 是防止一些开发组员在没有配置好 ESLint、Prettier 的情况下进行 git 相关操作。

npx husky-init && npm install

  当触发 pre-commit 时,默认执行的是npm test,我们我们可以做如下修改:

  • .husky / pre-commit
. "$(dirname -- "$0")/_/husky.sh"

npm run lint # 使用 ESLint 进行规范检测 并 修正代码

  上面是执行的是一个 npx 脚本命令,它会帮我们进行如下操作:

npx husky-init 内部操作

  当我们执行 npx husky-init 后,它会自动:

  • 帮我们安装 husky
  • 在 package.json 的 scripts 下新增"prepare": "husky install"
  • 新增了.husky文件夹及附属内容(pre-commit 钩子)

  我们也可以手动部署 husky 环境:

npm install husky -D
npm pkg set scripts.prepare="husky install"
npx husky add .husky/pre-commit "npm run lint"

# 2、lint-stadged

  -lint-staged (opens new window) 可以针对暂存的 git 文件运行 linter。而不是像前面一样,git commit 时,会 linter 项目的所有文件。

npm install lint-staged -D

  然后我们可以结合 husky 使用:

  • .lintstagedrc
{
  // "*.{js,ts,json,vue,jsx}": ["eslint --fix", "git add"]
  "*.{js,ts,json,vue,jsx}": "npm run lint"
}
npx husky add .husky/pre-commit "npx lint-staged"

# 3、yorkie

  如果我们在使用 vue-cli 构建项目时选择了使用 ESLint 时,并且在后续选项中选择了 Lint and fix on commit,那么 vue-cli 会自动帮我们完成相关配置(安装了lint-staged (opens new window),使用了@vue/cli-service 中的 yorkie (opens new window)

yorkie fork 自 husky(远古版本 2017 年 (opens new window) ) 并且与后者不兼容,更多内容见:Git Hook (opens new window)

// package.json
{
  // "scripts": {
  //   "precommit": "foo"
  // }

  // 这里的配置也可以单独写在lint-staged.config.js中
  "lint-staged": {
    "*.{js,jsx,vue,ts,tsx}": "vue-cli-service lint"
  },

  "gitHooks": {
    "pre-commit": "lint-staged"
  }
}

# 4、simple-git-hooks

  尤雨溪在 vue2 的源码中使用的是 yorkie,但在 vue3 中使用了 simple-git-hooks (opens new window)(对原 yorkie 做了一些升级)

最新的 vite、react、vitepress 也使用的这个

npm install simple-git-hooks -D
// package.json
{
  "lint-staged": {
    "*.{js,jsx,vue,ts,tsx}": "vue-cli-service lint"
  },

  // "gitHooks": {
  //   "pre-commit": "lint-staged"
  // }
  "simple-git-hooks": {
    "pre-commit": "npx lint-staged"
  }
}

  如果我们先前在项目中使用了 husky,应该这样安装 simple-git-hooks:

# 1、卸载husk
npm uninstall husky && git config --unset core.hooksPath # husky官方给的命令

git config core.hooksPath .git/hooks/ # simple-git-hooks官方给的命令
rm -rf .git/hooks

# 2、安装simple-git-hooks
npx simple-git-hooks

# 拓展:stylelint

  具体可以查看(这个可能会安装额外的 npm 包:如:stylelint-config-recommended-vue (opens new window)

Volar 描述:插件 (opens new window)Volar + ESLint + stylelint + husky 的使用示例 (opens new window)

开源项目:vue-vben-admin (opens new window)

# 五、Commit 规范

git 使用注意事项

  在使用 git 对项目进行管理时,其实也有一些注意事项值得我们关注:

  • 默认情况下 git 是忽略大小写的(文件名的大小写更改是不会被追踪的)
  • 新建的空文件夹默认是不会被跟踪的

  在进行 commit 版本时,我们可以为其加一个前缀来表示提交的内容属于什么范畴。

  具体来说,就是可以采用 AngularJS commit message format (opens new window)方案

Type 作用
feat 新增特性 (feature)
fix 修复 Bug(bug fix)
style 代码格式修改(white-space, formatting, missing semi colons, etc)
types 类型定义文件更改
perf 改善性能(A code change that improves performance)
refactor 代码重构(refactor)
revert 代码回退
docs 修改文档 (documentation)
chore 变更构建流程或辅助工具(比如更改测试环境)
ci 更改持续集成软件的配置文件和 package 中的 scripts 命令,例如 scopes: Travis, Circle 等
build 变更项目构建或外部依赖(例如 scopes: webpack、gulp、npm 等)
test 测试(when adding missing tests)

# 1、Commitizen

  -Commitizen (opens new window) 是一个帮助我们编写规范 commit message 的工具

安装:

# 安装Commitizen CLI 工具
npm install commitizen -g

# 初始化项目
commitizen init cz-conventional-changelog --save-dev --save-exact

使用:

使用 npx cz 代替 git commit

npx cz
阻止使用 git commit 命令:commitlint

cz-commitlint (opens new window)

# 安装
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# 配置
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"

# 2、verifyCommit.js ✨

  第一次看见是在 Pinia (opens new window) 中看到的,后来在 vue3 (opens new window) 中也看到了:

{
  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged && pnpm check",
    "commit-msg": "node scripts/verifyCommit.js"
  }
}
  • scripts/verifyCommit.js
// @ts-check
import chalk from 'chalk'
import { readFileSync } from 'fs'
import path from 'path'

const msgPath = path.resolve('.git/COMMIT_EDITMSG')
const msg = readFileSync(msgPath, 'utf-8').trim()

const commitRE =
  /^(revert: )?(feat|fix|docs|dx|style|refactor|perf|test|workflow|build|ci|chore|types|wip|release)(\(.+\))?: .{1,50}/

if (!commitRE.test(msg)) {
  console.log()
  console.error(
    `  ${chalk.bgRed.white(' ERROR ')} ${chalk.red(`invalid commit message format.`)}\n\n` +
      chalk.red(
        `  Proper commit message format is required for automated changelog generation. Examples:\n\n`
      ) +
      `    ${chalk.green(`feat(compiler): add 'comments' option`)}\n` +
      `    ${chalk.green(`fix(v-model): handle events on blur (close #28)`)}\n\n` +
      chalk.red(`  See .github/commit-convention.md for more details.\n`)
  )
  process.exit(1)
}

# 3、编辑器插件

  • vscode 中可以使用 git-commit-plugin 插件(推荐 😘)
  • IDEA 中可以使用 Git Commit Template 插件
  • webstorm 中可以使用 git-commit-template 插件
更新于 : 7/8/2024, 10:21:14 AM