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 钩子依赖:

bash
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'))"

预期输出:

text
Packages: +<N>
Done in <TIME>
true

<N> 和 <TIME> 会随锁文件、缓存及网络环境变化;最后的 true 表示 Husky 已创建提交前钩子文件。

配置 ESLint 与 Prettier

在项目根目录创建 eslint.config.mjs。配置顺序很重要:基础规则在前,Vue 与 TypeScript 规则随后,关闭格式冲突的配置最后加载。

js
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,将纯格式选择集中到一个文件:

js
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。这是片段示例,不要覆盖项目已有的名称、依赖和脚本:

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 改为以下内容:

bash
pnpm exec lint-staged

Husky 的初始化命令会创建 pre-commit 并写入 prepare 脚本;lint-staged 会把匹配到的暂存文件路径传给对应命令。代码文件先修复规则问题再格式化,可减少两个工具对同一文件反复改写。

验证配置是否生效

先对整个项目执行只读检查,确认当前代码库可以通过规则与格式验证:

bash
pnpm run lint && pnpm run format:check

预期输出:

text
> 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 和包管理器环境。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置代码检查与格式化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通