任先生的笔记库

提示

  如果团队开发间使用的都是 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 插件
更新于 : 8/7/2024, 2:16:31 PM

← 【代码格式化】 →

Apache License 2.0 | Copyright © 2022 lencamo All Rights Reserved | 蜀ICP备2022012538号-2