Vue / 系统课时

ESLint 与格式化规范

ESLint 与格式化规范

本课把 Vue 3 + TypeScript 项目的语法检查、格式化和提交前校验统一起来。完成配置后,团队可以用相同命令发现潜在错误、自动修复可修复问题,并避免因编辑器设置不同产生无意义的代码差异。

学习目标

  • 理解 ESLint、Prettier 各自负责的问题
  • 完成 Vue 3 与 TypeScript 的扁平化 ESLint 配置
  • 建立本地与持续集成可复用的检查命令

明确工具职责

ESLint 负责发现代码问题,例如未使用变量、错误的类型写法和不符合 Vue 规则的模板。Prettier 只负责排版,例如缩进、引号、换行和尾逗号。两者配合时,应让 ESLint 管质量,让 Prettier 管格式。

eslint-config-prettier 用于关闭与 Prettier 冲突的 ESLint 格式规则。它应放在 ESLint 配置末尾,避免同一段代码被两个工具按不同规则反复修改。

安装检查依赖

以下命令适用于已经通过 Vite 创建的 Vue 3 + TypeScript 项目。

bash
npm install -D eslint @eslint/js typescript-eslint eslint-plugin-vue globals prettier eslint-config-prettier

预期输出

text
added <N> packages, and audited <N> packages in <TIME>

<N> 和 <TIME> 会随项目依赖和网络环境变化。命令成功后,可在 devDependencies 中看到新增工具。

配置 ESLint

在项目根目录创建 eslint.config.js。如果项目没有启用 ES Module,可将文件名改为 eslint.config.mjs。

js
import js from '@eslint/js'
import eslintConfigPrettier from 'eslint-config-prettier'
import pluginVue from 'eslint-plugin-vue'
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,tsx,vue}'],
    languageOptions: {
      globals: globals.browser,
      parserOptions: {
        parser: tseslint.parser,
        extraFileExtensions: ['.vue']
      }
    },
    rules: {
      'vue/multi-word-component-names': 'off',
      '@typescript-eslint/no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }
      ]
    }
  },
  eslintConfigPrettier
)

这份配置检查 JavaScript、TypeScript 与 Vue 单文件组件,忽略构建和覆盖率目录,并允许使用下划线开头的占位参数。团队规则应集中写在 rules 中,不要依赖成员各自的编辑器设置。

配置格式与脚本

在根目录创建 .prettierrc.json。

json
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "none",
  "printWidth": 100,
  "endOfLine": "lf"
}

随后在 package.json 的 scripts 中加入检查命令。下面是片段示例,需要合并到项目现有的 scripts 对象中。

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

npm run format 会直接改写文件,适合开发阶段使用;npm run format:check 只检查不改写,适合提交钩子和持续集成。npm run check 只有在两项都通过时才返回成功状态。

运行并验证

先执行自动格式化,再进行完整检查。

bash
npm run format
npm run check

预期输出

text
> <PROJECT>@<VERSION> check
> npm run lint && npm run format:check

Checking formatting...
All matched files use Prettier code style!

ESLint 没有发现问题时通常不会额外输出错误信息,最终进程退出码为 0。若出现 no-unused-vars 或 Vue 模板规则错误,应优先修改代码;只有规则确实不符合团队约定时,才调整集中配置。

Tips:编辑器保存时自动格式化只能提升个人效率,不能替代仓库中的 npm run check。真正可复现的质量门禁必须由项目脚本定义。

常见配置问题

当 ESLint 无法解析 .vue 文件时,先确认 eslint-plugin-vue 已安装,并检查 Vue 扁平配置是否展开。出现 ESLint 与 Prettier 相互改写时,通常是 eslint-config-prettier 没放在最后,或仍启用了重复的格式规则。

不要把 dist、coverage 等生成目录纳入检查,否则会增加执行时间并产生无价值告警。也不要在单个文件顶部大量禁用规则,这会让团队规范逐渐失效。

本课总结

  • ESLint 检查代码质量,Prettier 统一排版,两者职责应分离
  • 扁平配置集中管理 Vue、TypeScript、忽略目录和团队规则
  • npm run check 可作为提交前与持续集成的统一质量门禁

下一课预告

下一课将搭建 Vitest 单元测试环境,配置浏览器模拟、测试目录、覆盖率,并编写第一个可运行的 Vue 组件测试。

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

目录与阅读设置

阅读设置

17

记录一个想法

ESLint 与格式化规范

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

登录哪都通