【明确目标】
本文提供一套完整的配置方案(支持 vscode + webstorm),配置后:
1、开发者编写代码过程中,会实时红线提示不符合 eslint 规范的代码
2、按下保存(command+s)代码自动按照 eslint 的规则进行格式化,不会发生规范检查(eslint)与自动格式化(prettier)冲突的情况
3、git 提交前,再次自动进行代码规范检查,确保提交到远程仓库的代码符合规范约定
【附】
这里为您提供一个实现了上述 目标,可直接使用的、一键生成规范配置的小工具:feflow-plugin-lint
欢迎使用,欢迎吐槽,我会努力优化哒!
第一部分:编辑器层面的准备工作
一、vscode
1、插件安装(3个)
eslint:让代码不符合约定规范时,能有红线提示
prettier:使得开发者使用快捷键(mac: shift+option+f,windows: shift+alt+f)格式化代码时,可以选择,根据 prettier 的规则来格式化(也就是,使用 prettier 作为 formatter)
editorconfig:读取 .editorconfig 规定的代码格式规范,覆盖掉当前编辑器的自定义配置。使得协作开发中,所有开发者的代码,都遵循 .editorconfig 的规范
2、配置 settings.json
配置方式如下:
编辑内容如下:
// 指定各类文件格式化默认用的 formatter,按需指定(这里可以指定prettier,是因为提前安装了prettier插件)
"[html]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[css]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[json]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[vue]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
也可以直接指定所有文件的默认 formatter(我们这里不建议这样做,原因后文会有说明):
"editor.defaultFormatter": "esbenp.prettier-vscode"
3、测试能力(下面操作,均以 mac 系统为例)
新建一个 js 文件,写一句反规范的测试代码:
按下 shift + options + f:
可以看到,这个时候,prettier 插件,已经帮助我们完成了代码的格式化。
它按照自己默认的那一套规则,格式化了我们的代码。比如使用双引号、加分号。
4、开启保存代码自动格式化
settings.json 添加一句话:
"editor.formatOnSave": true
编辑代码,保存,代码就会按照 prettier 的默认规则进行格式化。
至此,vscode 已经初步具备自动规范代码的能力。
但注意,它还不能对不规范的代码进行红线提示。这是 eslint 的能力,也需要项目层面的配置。
如果你使用的就是 vscode,可以直接跳到第二部分,去看项目层面要做的事。
接下来,我们看一下,webstorm 的使用者需要做哪些准备。
二、webstorm
webstorm 这种强大的 IDE,通常不需要我们做什么配置,直接内置了各种能力。但是也因为如此,很多对我们黑盒的东西,常常一知半解,稀里糊涂。
这里,我们先用上面的小例子,直接测试一下 webstorm 的自动格式化效果。
下面操作,均以 mac 系统为例。
格式化之前:
按下 option + command + L:
不知道你们的效果如何,反正,我这里就是没反应。。。
网查了半天,都说是快捷键冲突。但是按我的理解,有冲突,该有提示才对。
虽然不知道是和谁冲突了,索性设置一个自定义的格式化快捷键,再试吧。
设置方式如下:
这里,我把代码格式化快捷键,设置成了 shift + space。
设置完,没有冲突,ok 确认即可。
回到 index.js,按下 shift + space 测试一下:
可以看到,webstorm 默认,仅仅是帮我们整理了缩进。其他代码格式并未改变。
【注意】
这里,使用 webstorm 快捷键格式化,使用的规则,是在 webstorm 编辑器内部定义的。
开发者也可以自行修改这个规则。它根据不同的语言分类,为开发者提供了灵活的配置项:
但是,但是,但是
请注意。
这个配置是编辑器层面的,不同开发者之间,无法共享一套规范。
如果团队某成员使用了自己本地编辑器、自定义了规范,就会和其他成员的代码格式出现差异化。
所以我建议,不要使用这个规则去格式化你的代码!
为了团队协作考虑,请使用下面的方式,去格式化
【让webstorm和vscode一样,使用prettier默认规则格式化】
1、项目层面,安装 prettier
yarn add prettier -D
【注】
webstorm 的 prettier 配置依赖本地的 prettier 可执行文件。
而这种配置,理应属于项目层面,安装到全局并不合适。因此,这里需要混入一步项目层面的操作。
2、配置 webstorm
webstorm -> Preferences
搜索 file watcher,单击➕ 添加:
选择 Prettier:
这里设置成 Any,其他默认即可。更改后点击 OK:
【注】
顾名思义,大家应该看出来了。这里设置的,是一个 Prettier 的文件监听器。
监听什么呢?监听文件的变动,并,在文件变动时,使用 Prettier 默认的规则,对文件进行格式化。
说人话就是,这样设置之后,command + s 保存,代码会按照我们想要的、Prettier 的默认规则,自动格式化代码。
3、使用测试
回到 index.js,进行任意编辑、并按下 command + s:
ok,一切符合预期~
【第一部分总结】
完成第一部分,我们目前达到的效果是,两个编辑器,均可以在保存的时候,自动格式化代码。
请注意,这里,html、css、js、json 四类文件可以被自动格式化。(参考 settings.json 的 editor.defaultFormatter 配置)
并且,它们均使用了 Prettier 默认的那套规则。
第二部分:项目层面的配置
1、editorconfig 配置
(1)项目根目录下创建 .editorconfig
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
如果你还想进行更多的配置,可以参照官网:https://editorconfig.org/
【.editorconfig 作用解析】
编辑器配置。用于覆盖编辑器默认配置,以确保不同编辑器之间,代码格式的统一。
比如,使用 editorconfig,规定开发过程中,点击 tab 按钮,是以 tab 格式进行缩进,还是以 space 格式进行缩进。
如果没有约定,不同的编辑器,或者相同编辑器、不同开发者的配置存在差异,可能出现,有的人是 tab 缩进、有的人是 space 缩进的情况,造成代码风格的差异。
(2)使用测试
编辑 .editorconfig,设置 indent_size = 4。
分别用 vscode、webstorm 打开刚刚的 index.js,随意编辑,再次格式化(mac: shift+option+f,windows: shift+alt+f):
可以看到,Prettier 均按照 .editorconfig 的约定,对代码进行了格式化。
也就是说,这里,.editorconfig 的规则,覆盖掉了 Prettier 的默认规则。
同时,在这个规则下,当你编码过程中按下 tab 键,也会默认进行 4 格的缩进。
2、eslint 配置
【eslint 作用解析】
在代码编写的过程中,出现不符合规范的代码,进行红线提示。帮助开发者及时更正不符合规范的代码。
同时,提供命令行检查规范及 auto-fix 能力。
【注】
这里仅给出极简版最佳配置。如当前配置不符合项目需求,或期望了解更多,可以参考:
前端代码规范最佳实践:eslint+prettier+editorconfig+lint-staged 及 贴心的 eslint 各配置项详解
(1)安装 eslint + prettier + eslint-config-prettier + eslint-plugin-prettier
yarn add eslint prettier eslint-config-prettier eslint-plugin-prettier -D
(2)创建 .eslintrc.js
module.exports = {
root: true,
env: {
browser: true,
es6: true,
node: true,
},
extends: ['eslint:recommended', 'plugin:prettier/recommended'],
parserOptions: {
ecmaVersion: 2020,
sourceType: "module",
},
};
(3)观察效果
【vscode】
【webstorm】
【配置 webstorm,把红线搞出来~】
再来看下 webstorm 的效果:
(4)点击保存(mac: command+s,windows: ctrl+s)
代码自动格式化(按照 .eslintrc 配置的规则):
3、添加 lint-staged
【lint-staged 作用解析】
配合 husky 使用,在代码提交 git 前,进行规范性检查或格式化。如果代码不符合规范,则阻止提交。确保提交到 git 仓库的代码质量。
(1)安装husky + lint-staged
yarn add husky lint-staged
(2)配置 package.json
{
"scripts": {
"lint": "eslint .",
"prettier": "prettier --write ."
}
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
},
"lint-staged": {
// 这里的匹配规则,按需自定义。比如,检查 js + vue,可以这样:"*.{js, vue}"。详见:https://github.com/okonet/lint-staged
"*.js": [
"npm run prettier",
"npm run lint",
"git add ."
]
}
}
(3)配置 .eslintignore + .prettierignore + .gitignore
.eslintignore、.prettierignore 内容相同。一般需要忽略以下这些文件:
.DS_Store
node_modules
dist
# local env files
.env.local
.env.*.local
# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
.gitignore 参考如下:
.DS_Store
node_modules
dist
# local env files
.env.local
.env.*.local
# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
(4)观察效果
执行 git commit:
可以看到形如上面截图的报错。这是自动执行 prettier 格式化后,再执行 eslint 检查,仍然存在的代码规范错误。这类错误,就需要开发者手动进行处理了~
修改代码:
再次执行 commit 试试:
提交成功。
【阶段性成果总结】
至此,我们达成了以下这些能力:
(1)保存代码,任意代码都能够自动按照统一的规则(.editorconfig覆盖prettier默认规则得到的规则)进行格式化
(2)开发过程中,如果有书写不规范的代码,eslint 能够即时给出红线提示
(3)使用 git 提交代码时,会再次对所有 .prettierignore 以外的代码进行自动的 prettier 格式化
(这一步,是为了防止团队成员、自己本地未进行编辑器支持 prettier 的配置)
格式化后,再次进行自动的 eslint 规范性检查,检查通过,才允许提交。否则,进行错误提示
(这一步,是为了检查出 prettier 不能够自动修复的规范问题。如:变量定义但未使用)
4、自定义代码规范
默认的规则,必然会存在一些不符合我们开发习惯的情况。因此,自定义规范,必然是刚需。
(1)创建.prettierrc
{
"singleQuote": true
}
前面可以看到,Prettier 默认的规则是,使用双引号。这里,我们要求字符串使用单引号。
(2)效果测试
配置后,打开 index.js,任意编辑后,点击保存:
【注】
项目目录下的 .prettierrc 文件,具有格式化规则的最高优先级,它会覆盖掉默认的 prettier 规则以及 .editorconfig 的规则。
【总结】
至此,我们完成了基于 eslint:recommended 规范的 eslint 检查 + prettier 格式化配置。
这套配置能够强有力地保证团队协作中的代码规范性,同时,兼容 vscode、webstorm 两大编辑器。
具体能力如下,再次列举:
(1)保存代码,任意代码都能够自动按照统一的规则进行格式化
(统一的规则:.eslintrc 中配置的 rules。即:editorconfig覆盖 prettier 默认规则、.prettierrc 覆盖.editorconfig,得到的规则)
(2)开发过程中,如果有书写不规范的代码,eslint 能够即时给出红线提示
(3)使用 git 提交代码时,会对所有 .prettierignore 以外的代码进行自动的 prettier 格式化
(这一步,是为了防止团队成员、自己本地未进行编辑器支持 prettier 的配置)
格式化后,再次进行自动的 eslint 规范性检查,检查通过,才允许提交。否则,进行错误提示
(这一步,是为了检查出 prettier 不能够自动修复的规范问题。如:变量定义但未使用)
第三部分:以 vue 项目为例,配置实际项目
1、安装 eslint-plugin-vue
yarn add eslint-plugin-vue -D
2、配置 .eslintrc.js
添加 'plugin:vue/essential':
给 eslint 添加 vue 插件,是为了让 eslint 认识 vue 的语法,并按照 vue/essential 这套规则,进行检查。
3、创建任意 vue 文件,编写不符合规范的代码,观察效果。这里不再演示。
【后记】
关于 eslint、prettier、editorconfig 以及 eslint-config-prettier、eslint-plugin-prettier 的作用与能力讲解,
可以参考:前端代码规范最佳实践:eslint+prettier+editorconfig+lint-staged