likes
comments
collection

统一开发环境、了解配置原理(上)

作者站长头像
站长
· 阅读数 24

作为一个组件库,也是一个比较大的项目,在开发组件库的过程中一定会出现多人协作的过程,所以我们需要在很多方面对其进行限制,否则就可能出现不同人员不同的开发习惯与编码风格造成项目的混乱,或者不同的编辑器配置都会造成影响,包括在git提交的过程中也会造成随意提交信息的一系列问题,所以,基于此,我们在本章节内容中。将对这些方面进行限制,并告诉大家这些不同的插件的作用以及如何使用。

本章节的内容不仅仅支持的是本次组件库的开发,也适用于所有日常开发的项目,当然,本次项目的主要技术栈是基于vite+vue的技术架构来实现的。

统一代码质量Eslint

在此之前,我写过一些代码质量校验的文章,可以在学习前进行参考:

对这块儿东西大家应该都不陌生了,日常的项目中,或多或少一定会接触到,我们需要使用eslint对项目进行代码质量的校验,何为代码质量校验,例如,我们定义了不使用的变量,引入了不使用的组建,使用了不严格的var这些问题都算是代码质量,类似这些在开发环境就很容易产生但是又容易被开发者忽视的信息由工具检测出来就非常轻松了,所以首先我们先安装这个包:

pnpm i eslint -D -w

这种校验只需要在开发环境使用,所以下载在开发环境中即可,同时,因为我们是Monorepo项目,所以我们需要在后面加-w,如果是普通的单仓库项目是不需要加后面的内容的,这里做个简单说明。

下载完之后,我们需要生成一个配置信息。eslint将根据我们配置的信息对项目进行校验,这个配置信息的方式有很多种,如果你日常看到的都是别人编写好的,那么你得明白他的配置原理,一般对于这些工具来说,配置文件都是以比如config.jsrcyaml结尾或者直接写入package.json当中,所以有时候当你的配置没生效的时候,可能是别的地方也配置了,导致覆盖了你的配置,你需要去这些地方看看是否有冲突,在eslint中,有如下这些种类的配置信息,如果出现多份配置,将会被优先级高的配置所覆盖。

1 .eslintrc.js
2 .eslintrc.yaml
3 .eslintrc.yml
4 .eslintrc.json
5 .eslintrc
6  package.json

我们可以手动在这些地方创建房间,还有一种,通过cli工具来创建,我们可以在项目中使用npx eslint --init调用cli工具进行初始化一份模板,在这之中,会选择很多问题,我们按自己的需要选择即可:

统一开发环境、了解配置原理(上) 一般选择完之后会自动帮我们下载相关的依赖,但是由于我们的Memorepo原因我们需要自己加-w下载,所以我们自己进行下载:

pnpm i eslint-plugin-vue@latest @typescript-eslint/eslint-plugin@latest @typescript-esli

我们可以看到一共下载了三个包分别解释下,第一个eslint-plugin-vue,看过上面的基础文章的应该知道,eslint默认只支持检测js文件,所以如果Vue项目需要支持的话就需要这个插件,让其支持检测.vue的文件,同理如果你是别的类型的也需要去下载别的插件,比如jsx,后面两个看命名就知道,因为我们是Typescript项目,所以,要支持ts类型文件就得下载这个插件,最后一个插件呢看命名parser解析器,所以是用来解析ts的语法的。

此时我们可以看到根目录出现了一个.eslintrc.js文件,这个就是配置文件了,里面已经根据我们的选择生成了一份基础模板:

module.exports = {
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:vue/vue3-essential",
        "plugin:@typescript-eslint/recommended"
    ],
    "overrides": [
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "vue",
        "@typescript-eslint"
    ],
    "rules": {
    }
}

上面这个配置表的所有字段,如果有不了解的,之前去看前面提到的两篇文章,里面都有详细的介绍,我们就不废话了,直接添加一个规则,比如不允许使用console,只需要在rules里面添加:

"rules": {
   'no-sonsole': 2
}

然后我们看看有没有生效,进入到example/app.vue,到script中写一个console我们发现貌似没有报错,但是在开头却出现了这样的提示:

统一开发环境、了解配置原理(上)

为什么会这样呢,因为eslint默认使用Espress作为解析器,我们是vue文件当然不能解析成功,所以我们需要更改配置:

"parser": "vue-eslint-parser",
"parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module",
    parser: '@typescript-eslint/parser'
},

我们将解析器parse项改为vue-eslint-parse用于解析vue这个选项在eslint-plugin-vue中已经有了,所以不需要安装,同时再将ts需要的parser: '@typescript-eslint/parser'放入到parseOptions中,此时上面的错误将消失不见,这时,我们禁止console的提示便会出现,如下:

统一开发环境、了解配置原理(上)

结合开发环境提示

此时问题出现,这个一定会出现么,很明显,不一定,因为这个提示是来自编辑器,所以,如果你要编辑器提示这个,你的首先安装eslint插件,这里的编辑器使用的是vscode,也是目前前端最主流使用的编辑器了,我们只有安装了这个插件才能实现提示,否则,是没有这个红线的,同时,配置规则的时候是三种等级0,1,2对应的也可以是off,warn,error,表示的则是关闭规则,警告,错误三个等级,关闭等于没了,警告是黄线,错误是红线。

同时我们还需要注意一定,确定自己的配置是正常的,如果是错误的,那你写再多规则,也没用,怎么样确定正常呢,我们如果安装了插件,在右下角会有一个eslint的提示,我们点击打开,将会出现如下信息:

统一开发环境、了解配置原理(上)

此时表示已经正常启动,上面还显示node版本,那如果是错误的时候呢,比如,我们随便配置一个插件名称,给插件中配置一个aaa,然后保存,然后你就会发现此时就会报错如下:

统一开发环境、了解配置原理(上)

告诉我们没有找到这个模块,所以,如果你没有去检查你的配置是否正常,可能你在项目里写了很多规则不生效你还很迷惑,在这个地方,你可以知道自己配置错了什么信息,或者少安装了什么依赖,只有这里是检测通过后,插件才能正常工作。

还有一点,在vcode中,配置这些信息是有缓存的,如果你改变了这个报错还在,那么可以使用comman+shift+p调出面板,再输入reload对窗口进行重载,这样就可以让其重新检测一次配置信息。

同样此时还有问题,如果我们的用户没有安装这个插件怎么办呢?编辑器不提示报错,我们有办法让他在开发过程中报错么,当然也是可以的:我们可以在他页面上为开发者这样显示错误:

统一开发环境、了解配置原理(上)

这样即使没有插件,也能让用户看到错误,当然,这样的话可能会对开发的严格性大大提高,需要考虑之后加入此功能,如何实现呢,在使用vite过程中,我们可以加入这个插件:

pnpm i vite-plugin-eslint -D

然后在vite.config.js当中引入这个插件使用即可,简单两步就完成了这个需求了,当然,他也是有配置参数的,不过默认就会检测' /*.js', ' / .jsx', '**/ .ts', ' /*.tsx', ' / .vue', '**/ .svelte'这些文件,所以我们可以省略掉,具体可以看看文档。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import viteEslint from 'vite-plugin-eslint';

export default defineConfig({
  plugins: [vue(),viteEstend()],
})

此时我们就拥有了使用eslint的能力,但是呢很明显我们还缺少很多规则,规则的配置各取所需,我们在文中就不着重讲了,后续可以到仓库中查看我定义的规则,我也为每一条规则添加了详细的注释。

添加校验命令

同时在我们的script中增加两个脚本用于检测和修复:

"lint:fix": "eslint . --fix",
"lint:eslint": "eslint .",

调用脚本就可以去进行检测或者修复了,当然我们并不是所有文件都一样需要检测,比如打包之后的文件,或者引入的三方库或者包,所以我们可以在根目录创建一个.eslintignore的文件,在这里声明的文件就可以不需要进行检测了,具体的项目这一块儿并不同,大家按照实际需求更改。

至此我们已经了解清楚了eslint的使用原理过程以及检测配置等步骤,正常来讲,我们只需要添加配置规则或者使用开源的规则就可以对项目进行规范了。

我们可以开始下一个工具的使用了

统一代码风格校验Prettier

代码质量其实更多的是语法方面的校验,如果想要我们的风格实现统一,比如,一行多少字,要不要分号,要不要双引号等等这些关于代码风格的统一需要用到prettier,其是专注于代码风格的一个工具,eslint本身也有少量的代码风格规则,但是在更多场景下,他无法支持,所以我们直接下载它,

pnpm i prettier -D -w

下载完之后同理,我们在根目录需要创建一个他的配置文件和忽略文件,分别是prettier.config.js.prettierignore文件,他的配置规则呢,可以参考官网Options · Prettier,可配置的选项并不是很多,可以很快配置好,同理,prettier的配置文件也可以是多种,具体的类型参考Configuration File · Prettier,在我们看到不同类型的文件的时候其实大同小异,都是一个提供配置参数的文件罢了。

我们在git项目里提供了我得配置并且都加入了中文注释,如果想要自己配置也可以从上面的配置地址查看更多配置:

module.exports = {
  printWidth: 120, //最大单行长度
  tabWidth: 2, //每个缩进的空格数
  useTabs: false, //使用制表符而不是空格缩进行
  semi: true, //在语句的末尾打印分号
  vueIndentScriptAndStyle: true, //是否缩进 Vue 文件中的代码<script>和<style>标签。
  singleQuote: true, //使用单引号而不是双引号
  quoteProps: 'as-needed', //引用对象中的属性时更改 "as-needed" "consistent" "preserve"
  bracketSpacing: true, //在对象文字中的括号之间打印空格
  trailingComma: 'none', //在对象或数组最后一个元素后面是否加逗号(在ES5中加尾逗号)
  arrowParens: 'avoid', //箭头函数只有一个参数的时候是否使用括号 always:使用  avoid: 省略
  insertPragma: false, //是否在文件头部插入一个 @format标记表示文件已经被格式化了
  htmlWhitespaceSensitivity: 'strict', //HTML 空白敏感性 css strict ignore
  endOfLine: 'auto', //换行符使用什么
  tslintIntegration: false //不让ts使用prettier校验
};

比如我们配置了这些信息,我们想看看生效没有,比如我们配置了在末尾需要加分号,我们随意找个地方写个不带分号的看看提示:

你会发现没有任何提示,没错,是我们没生效么?显然不是,首先第一点,和Eslint一样,我们在使用的时候需要下载prettier-eslint插件配合使用,但是此处依然不会报错,但是我们在此时右键,选择使用格式化文档,此时的选项里面有一项是prettier eslint的格式化选项,我们使用这个选项格式化,就可以完成我们对我们所配置的风格的还原了:

统一开发环境、了解配置原理(上)

但是如此显得过于麻烦了,同时,由于eslint有自己的规则,还会造成格式化之后Eslint就会报错,所以出现下面的问题

第一,我们需要每次手动去格式化,

第二,我们的语法根本不提示

第三pretiier的配置和eslint有冲突

解决冲突

为了解决这三个问题,所以我们需要让其与Eslint相结合,

此时我们需要用到两个新的包

  • eslint-config-prettier: 会关闭掉所有的eslint关于格式化的配置
  • eslint-plugin-prettie: 会将prettier配置为eslint的插件,让其成为eslint的一个规则,这样,不满足prettier规范的地方就会报错提示了。

知道这两个的包的作用了我们就对齐进行下载:

pnpm i eslint-plugin-prettier eslint-config-prettier -D

并且将这这个配置规则和插件添加到我们的配置当中,此时呢,我们还没有启用这个规则,要启动规则很简单,我们只需要在rules里面添加一项配置'prettier/prettier': 2,此时就会出现代码风格的提示了,如下图。

统一开发环境、了解配置原理(上)

如果配置完没有生效的话,记得重载窗口,当然还有一种方式帮你开启这个,我们可以使用插件中携带的配置'plugin:prettier/recommended',点开源码可以看到如下配置:

{
  "extends": ["prettier"], // 使用eslinst-config-prettier中的配置项
  "plugins": ["prettier"], // 注册该prettier插件
  "rules": {
    "prettier/prettier": "error", // 在eslint中运行prettier,并启用该插件提供的规则
    "arrow-body-style": "off", // 关闭规则
    "prefer-arrow-callback": "off" // 关闭规则
  }
}

它帮我们分别在配置项和插件项引入了这两个包,同时在rules中开启了prettier规则,并关闭了两条规则,所以除了上面我们手动配置的情况下,我们可以直接在extends下面继承plugin:prettier/recommended就可以完成上述配置,当然这里是告诉大家实现这个方法的原理,同时我也更推荐自己手动去配置,在别人拿到之后可以有迹可循,使用继承别人配置好的方式虽然方便,但也增加一些迷惑性。

自动修复

此时,我们已经可以将两者很好的配合起来使用了,在这之中呢,不管是eslint还是perttier上面拥有🔨标志的规则都表示可以被自动修复,所以我们可以结合编辑器再完成一步,保存的时候自动修复掉所有可以修复的错误。

对于编辑器而言,我们在本地单独设置的只能给自己使用,别人去开发项目的时候无法实现这一步,所以呢,我们可以将这些配置也放在项目中,对于vscode的配置,我们只需要在根目录添加一个.vscode的文件夹,并在其中创建一个.settings.json的文件,就可以去更改编辑器的配置了,同时编辑器也会以这里的权限为最高,我们可以在这个配置文件中规定很多东西,包括编辑器的风格,字体等等,但是显然这样不合理,我们不想对不同用户去修改很多东西,我们只去配置一个小小的功能就是保存的时候,自动修复eslint的错误即可,我们添加如下:

  "eslint.validate": ["html", "vue", "javascript", "jsx"],
  "emmet.syntaxProfiles": {
    "vue-html": "html",
    "vue": "html"
  },
  "eslint.alwaysShowStatus": true,
  "eslint.quiet": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.fixAll": true
  }
}

主要是这个配置source.fixAll.eslint,将其设为true就可以实现保存的时候自动修复了,对于详细的规则配置详见仓库,后续更多规则在开发中再进行变更。

针对组件库的改动

上述的内容是可以适用于任何项目的,但是针对于我们的组件库呢,可以进行一些整理,因为我们是Monorepo架构,我们会去创建一个子项目,将所有配置全部写入子项目当中,同时将其做为一个子模块的情况下,不仅仅当前项目,在以后别的项目同样可以使用,我们可以对齐单独发包。

最终在我们使用的时候,只需要这样直接继承就可以使用,非常便捷:

{
  "root": true,
  "extends": ["@brain-ui/eslint-config"]
}

同时需要注意的是,我们开头说过,eslint默认只支持js格式的文件,所以默认的规则也都是基于js的,我们分别下载了vuets的额外编译器,同样也为我们带来了这两种其他格式的规则,我们可以在这三个地方查看不同的规则

所以你日常看到的很多规则可能来自于不同的包,你在eslint官网并不能全部找到,这一点你需要知道,同时为了方便大家查看,我将其单独分离成为了三个文件,你只需要去查看不同的文件即可看到不同的规则,结构如下:

eslint-config
├── eslint.rules.js
├── index.js
├── package.json
├── ts.rules.js
└── vue.rules.js

最终我们只需要在入口页引入不同的规则即可,如果大家后续项目参考我这样的写法,可以在不同的文件下去看看对应的规则,在里面也会有详细的注释。

const eslintRules = require('./eslint.rules');
const tsRules = require('./ts.rules');
const vueRules = require('./vue.rules');

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: ['plugin:vue/vue3-essential', 'prettier', 'plugin:@typescript-eslint/recommended'],
  overrides: [],
  parser: 'vue-eslint-parser',
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    parser: '@typescript-eslint/parser'
  },
  plugins: ['vue', '@typescript-eslint', 'prettier', 'plugin:prettier/recommended'],
  rules: {
    ...eslintRules,
    ...tsRules,
    ...vueRules
  }
};

最后我们也同样在package.json当中配置一条修复命令用于修复风格相关内容

"lint:prettier": "prettier --write ."

总结

此时我们已经完成了统一开发环境的一小步,本章内容不仅仅针对组件库的开发,同样适用于我们个人的项目,学习本节内容,更多的是学习和了解每一个包的用初以及如何搭配使用,这样可以让我们从0开始的时候轻松完成。

下一节的内容我们依然继续去统一开发环境,限制文件命名,通知提交规范,统一样式规范等其他开发环境的限制,让我们的项目一致性更加的健壮。

本节更新内容较多,详细代码地址依然更新到此仓库 GitHub - longyanjiang/brain-ui: A Vue.js 3 UI Library for Web

本期专栏历史文章