（详）Vue3 + Typescript 项目配置 eslint + prettier + husky + lint-staged

1，前言

1.1，eslint 和 prettier 的关系

prettier 是代码格式化工具，专注于代码的格式化和美化。它的主要目标是自动格式化代码，以确保代码风格的一致性。配置简单，执行速度快。

eslint 是静态代码分析工具。可以识别和报告 js 代码中的错误、潜在问题以及不符合特定编码风格的地方，通常用于确保代码质量。主要功能：

• 错误检查；
• 代码风格，相比较 prettier，对代码风格的检查更严格，比如是否允许声明但未使用的变量；
• 插件系统，比如可集成针对 .vue 文件或 .tsx、.jsx 文件的检查。

1.2，Node.js 版本的问题

eslint + prettier + husky + lint-staged 这4个 npm 依赖对 Node.js 的版本都有要求，需要安装适配的。

通过 这篇文章 可以确定适配本地 Node.js 版本的依赖。

下面都是以 Node.js@v16.20.2 举例：

1，eslint

1.1，安装

查看 eslint 官方文档 发现，无法使用下面的命令安装，因为默认会安装最新版本 v9.9.1，不匹配本地 Node.js 版本。

npx eslint --init
npm init @eslint/config@latest

所以手动安装版本 v8.57.0，

npm i eslint@8.57.0 -D

因为要使用 Typescript 开发，所以需要安装 typescript-eslint，这里选择适配的版本 v7.2.0，

npm i @typescript-eslint/eslint-plugin@7.2.0 @typescript-eslint/parser@7.2.0 -D

1.2，配置文件

新建 .eslintrc.json 或 .eslintrc.js 文件，添加如下配置，参考官方文档的示例

{
    "root": true,
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": { "project": ["./tsconfig.json"] },
    "plugins": [
        "@typescript-eslint"
    ],
    "rules": {},
    // 忽略的文件
    "ignorePatterns": ["src/**/*.test.ts", "src/frontend/generated/*"]
}

也可以将要忽略的文件放到 .eslintignore 中。另外，一般也不用 eslint 检查图片和样式。

dist

auto-imports.d.ts
components.d.ts

*.png
*.svg
*.scss
*.css

1.3，集成对 vue 文件的配置

需要添加对 .vue 文件的解析器，否则无法解析（react 同理）。这里使用 eslint-plugin-vue，eslint 检测 .vue 文件相关的问题，都可以在官网规则中找到。

npm i eslint-plugin-vue -D

同时参考官方文档，修改 .eslintrc.json 如下：

{
  "root": true,
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:vue/vue3-recommended"
  ],
  "parser": "vue-eslint-parser",
  "parserOptions": {
    "parser": "@typescript-eslint/parser"
  }
}

1.4，在 package.json 中添加命令

{
	"scripts": {
		"eslint": "eslint src/** --cache",
		"eslint:fix": "npm run eslint --fix",
	}
}

配置项 --cache ：只检查已更改的文件。所以第一次做 eslint 检查时应去掉该选项来检查全局。
配置项 --fix ：自动修复。

也可以使用配置项 --ext，指定要检查的文件扩展名，不过一般也是在 .eslintignore 中配置不检查的文件类型。

eslint src/** --ext .js, .ts

这样，关于 eslint 的配置就完成了，运行 npm run eslint 结果如下，可以看到检测出的问题。CTRL+ 鼠标左键 可以跳转对应文件。

而这种稍微复杂的语法，使用 npm run eslint:fix 是无法修复的，需要手动修复。

2，prettier

2.1，安装

查看 官方文档 发现，如果要集成 eslint，还需要安装 eslint-config-prettier

npm i prettier eslint-config-prettier -D

2.2，配置文件

添加配置文件 .prettierrc.js，下面是我常用的一些配置，更多配置看官方文档。

const config = {
	printWidth: 180,
	semi: true, // 使用分号
	trailingComma: "es5", // 使用尾随逗号
	arrowParens: "avoid", // 箭头函数一个参数不使用括号
	htmlWhitespaceSensitivity: "ignore", // 忽略 HTML 中的空白
	endOfLine: "crlf", // 换行符为 \r\n
	// 其他默认值
	// tabWidth: 2, // 缩进大小
	// useTabs: false,  // 使用空格代替制表符
	// singleQuote: false, // 使用单引号
	// bracketSpacing: true, // 使用空格分隔括号
	// bracketSameLine: false, // > 单独起一行
	// proseWrap: "preserve", // 纯文本不自动换行
	// singleAttributePerLine: false, // 不将单个属性放在单独的一行
	// vueIndentScriptAndStyle: false, // Vue 不缩进 script 和 style
};

export default config;

同时为了避免和 eslint 的冲突，需要使用 eslint-config-prettier 替换掉 eslint 的部分规则，修改 .eslintrc.json 添加 prettier 的配置：

{
	"extends": [
		"eslint:recommended", 
		"plugin:@typescript-eslint/recommended", 
		"plugin:vue/vue3-recommended", 
		"prettier"
	],
	// ...
}

添加忽略文件 .prettierignore，它的默认值是

**/.git
**/.svn
**/.hg
**/node_modules

注意，默认情况下 .gitignore 中的文件，也不会被格式化。

2.3，在 package.json 中添加命令

{
	"scripts": {
		"prettier": "prettier --check .",
		"prettier:fix": "prettier --write . --list-different",
		"lint": "npm run eslint && npm run prettier",
		"lint:fix": "npm run prettier:fix && npm run eslint:fix"
	}
}

. 表示项目根目录下所有文件。目标目录必须添加，否则无效。
--write 表示修复。
--list-different 表示输出日志中，只展示发生变化的文件。

这样，关于 prettier 的配置就完成了，运行 npm run prettier:fix，就会检查并修复：

3，husky + lint-staged

目的：为了统一整个团队的代码规范，所以在 git commit 时，需要自动执行一次检查并进行格式化，无法修改的问题也要输出警告。

要实现这个能力，需要用到 Git Hooks 和 lint-staged。

3.1，husky 和 Git Hooks

Git hooks 是 Git 一个功能，它们是一些在特定重要动作发生时自动执行的脚本。这些脚本被存储在 Git 仓库的 .git/hooks 目录下。Git 提供了多种类型的 hooks，例如：

• pre-commit：在 commit 之前运行，可以用来检查代码风格、运行测试等。
• pre-push：在 push 之前运行，可以用来检查远程状态、防止推送不符合要求的代码等。
• post-merge：在 merge 之后运行，可以用来自动安装依赖、更新子模块等。

Husky 是一个用于管理 Git hooks 的 npm 依赖，它增强了 Git hooks 的功能，配置也比较方便。

同样安装适配本地 Node.js@16.x 的版本：

npm i husky@8.0.3 --D

初始化 husky，正常情况下可通过 npx husky init 命令实现，但它只对最新版本（v9.x）有效，所以我们手动实现。

npx husky install

会在项目根目录下生成

添加 pre-commit，

npx husky add .husky/pre-commit 'npx lint-staged'

会在 .husky/ 目录下生成一个文件 pre-commit，

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

现在我们在执行 git commit -m "xxx" 就会触发执行 pre-commit 脚本了。

另外，注意到有的 husky 写法是在 package.json 中添加配置，这个是 husky@4 版本 的做法，已经过时了。

{
  "husky": {
    "hooks": {
      "pre-commit": "xxx"
    }
  },
}

这样，husky 相关的配置就完成了。

3.2，lint-staged

目的：它允许在 Git 暂存区（staging area）中的文件上运行脚本。

这意味着可以在文件被 commit 到仓库之前，自动运行一些检查或格式化命令。比如用于代码风格一致性、代码质量或执行其他验证。

注意，只对暂存区的文件生效。

同样的，安装适配 Node.js@16.x 版本的，

npm i lint-staged@14.0.1 -D

在 package.json 中增加配置，

{
	"lint-staged": {
		"*.{js, ts, vue}": [
			"eslint src/** --fix",
			"prettier --write --list-different"
		],
		"*.{json,md,html,css,scss,sass}": [
			"prettier --write --list-different"
		]
	}
}

注意，这里的 prettier --write 后没有加目标目录，这是允许的。

这样，lint-staged 相关的配置就完成了。

---

至此，现在运行 git commit -m xxx 就会检查并尝试修复一次代码，如果有问题会 commit 失败！

4，其他问题

4.2，husky 配置文件问题

注意，当执行 npx husky install 时生成的文件中，是有 .gitignore 文件的，这样会导致这个 husky.sh 无法上传到远程仓库，这样其他组员拉取代码后，husky 是不会生效的。

所以记得将这个 .gitignore 文件删掉！

4.1，no-unused-vars 的问题

1，@typescript-eslint 的配置项 @typescript-eslint/no-unused-vars 用于检测声明但未使用的变量。

但有一种情况比较特殊：解构赋值。常用于从一个对象中剔除一些属性：

const { id, type, ...rest } = options

在上面的例子中，id 和 type 之后也不会用到，也算是 no-unused-vars。所以需要特殊处理。

解决：

在 typescript-eslint 官方文档 中有说明，它是继承了 eslint/no-unused-vars 的规则，其中可配置规则以忽略特定的变量：

{
  "rules": {
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
         // 忽略解构赋值产生的变量
        "ignoreRestSiblings": true
      }
    ]
  }
}

---

以上。