Vue / 系统课时
配置代码检查与格式化
配置代码检查与格式化
本课为 Vue 3 与 TypeScript 项目接入 ESLint、Prettier、Husky 和 lint-staged,形成“本地检查、自动格式化、提交前拦截”的完整链路,并给出可直接验证的配置。
学习目标
- 明确 ESLint、Prettier 与提交前钩子的职责边界
- 使用 Flat Config 配置 Vue 3 和 TypeScript 检查规则
- 让暂存区文件在提交前自动检查和格式化
明确工具职责
ESLint 负责发现代码问题并执行团队规则,Prettier 只负责稳定的代码排版;eslint-config-prettier 应放在 ESLint 配置末尾,用于关闭与格式化器冲突的规则。提交前阶段再由 Husky 触发 lint-staged,只处理本次暂存的文件。
这套分工避免让 ESLint 和 Prettier 同时修改同一种格式规则,也避免每次提交都扫描整个仓库。完整的执行关系如下:

安装开发依赖
在项目根目录安装检查、格式化与 Git 钩子依赖:
pnpm add -D eslint @eslint/js eslint-plugin-vue typescript-eslint globals prettier eslint-config-prettier husky lint-staged
pnpm exec husky init
node -e "const fs=require('node:fs'); console.log(fs.existsSync('.husky/pre-commit'))"预期输出:
Packages: +<N>
Done in <TIME>
true<N> 和 <TIME> 会随锁文件、缓存及网络环境变化;最后的 true 表示 Husky 已创建提交前钩子文件。
配置 ESLint 与 Prettier
在项目根目录创建 eslint.config.mjs。配置顺序很重要:基础规则在前,Vue 与 TypeScript 规则随后,关闭格式冲突的配置最后加载。
import js from '@eslint/js'
import pluginVue from 'eslint-plugin-vue'
import eslintConfigPrettier from 'eslint-config-prettier'
import globals from 'globals'
import tseslint from 'typescript-eslint'
export default tseslint.config(
{
ignores: ['dist/**', 'coverage/**'],
},
js.configs.recommended,
...tseslint.configs.recommended,
...pluginVue.configs['flat/recommended'],
{
files: ['**/*.{ts,vue}'],
languageOptions: {
globals: globals.browser,
parserOptions: {
// 让 Vue 单文件组件中的 <script lang="ts"> 使用 TypeScript 解析器
parser: tseslint.parser,
},
},
rules: {
'@typescript-eslint/no-explicit-any': 'warn',
'vue/multi-word-component-names': 'off',
},
},
eslintConfigPrettier,
)创建 prettier.config.mjs,将纯格式选择集中到一个文件:
export default {
semi: false,
singleQuote: true,
trailingComma: 'all',
printWidth: 100,
}ESLint Flat Config 使用根目录的 eslint.config.* 导出配置数组;Vue 与 TypeScript 插件都提供可组合的 Flat Config。Prettier 配置负责统一排版,eslint-config-prettier 负责关闭可能与格式化器冲突的 ESLint 规则。
接入脚本与提交前检查
将下面字段合并进现有 package.json。这是片段示例,不要覆盖项目已有的名称、依赖和脚本:
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
"format:check": "prettier --check .",
"prepare": "husky"
},
"lint-staged": {
"*.{js,mjs,cjs,ts,tsx,vue}": [
"eslint --fix",
"prettier --write"
],
"*.{json,md,yml,yaml,css,scss}": "prettier --write"
}
}把 .husky/pre-commit 改为以下内容:
pnpm exec lint-stagedHusky 的初始化命令会创建 pre-commit 并写入 prepare 脚本;lint-staged 会把匹配到的暂存文件路径传给对应命令。代码文件先修复规则问题再格式化,可减少两个工具对同一文件反复改写。
验证配置是否生效
先对整个项目执行只读检查,确认当前代码库可以通过规则与格式验证:
pnpm run lint && pnpm run format:check预期输出:
> eslint .
> prettier --check .
Checking formatting...
All matched files use Prettier code style!随后修改并暂存一个 .vue 或 .ts 文件,再正常提交。格式可修复时,lint-staged 会更新暂存内容并继续提交;存在无法自动修复的 ESLint 错误时,命令返回非零状态,提交会被阻止。
处理典型失败
出现 .vue 解析错误时,先确认 Vue 推荐配置已经加载,并检查 parserOptions.parser 是否指向 TypeScript 解析器。若大量格式规则互相冲突,确认 eslint-config-prettier 位于配置数组末尾。
提交时没有执行钩子,可重新运行 pnpm run prepare,并确认当前目录属于包含 .git 的仓库。终端检查正常但图形化 Git 客户端提示找不到 pnpm 时,通常需要让客户端加载与终端一致的 Node.js 和包管理器环境。