终极进化！拥抱 ESLint v9，让你的 Vue 3 + Vite 项目“刀枪不入” ✨

原创于 2025-10-30 19:21:29 发布 · 1.2k 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#vue.js #前端 #javascript

Vue 3 + Vite + Element Plus 专栏收录该内容

14 篇文章

订阅专栏

🚀 终极进化！拥抱 ESLint v9，让你的 Vue 3 + Vite 项目“刀枪不入”

嘿，各位前端战友们！👋 你是否还在为 npm run build 时才发现一堆 TypeScript (TS) 错误而烦恼？是否还在忍受团队成员提交的代码风格五花八门？

今天，我将带大家完成一次前端工程化的“终极进化”——为你的 Vue 3 + TS + Vite 项目，配置上最新、最强大的 ESLint v9。

我们将一起搭建一个全流程、立体化的代码质量保障体系，让你在写代码的那一刻，就能拥有“实时纠错”的超能力！

🎯 我们的目标：一个“刀枪不入”的开发环境

我们追求的，不仅仅是代码能跑，而是：

实时反馈 🚨：在 VSCode (Visual Studio Code) 中写代码时，任何 TS 错误或不规范的写法，都应立即被红色波浪线标记。
风格统一 🎨：整个项目的代码风格（单双引号、分号等）保持一致。
质量门禁 🛑：有问题的代码，既不能被提交到 Git 仓库，也不能被打包部署到生产环境。

要实现这个目标，我们需要请出两大“神器”：ESLint 和 VSCode ESLint 插件。

🕵️‍♂️ 踩坑实录：ESLint v9 的“新世界”

在配置过程中，我们遭遇了一连串的“神秘事件”，如果你也遇到了，别慌，你不是一个人！

Error: Could not find config file (找不到配置文件)
- 真相：我们还在使用旧的 .eslintrc.js。而我们安装的 "eslint": "^9.x" 版本，已经全面拥抱了全新的、不兼容的 “flat config” 格式，其默认配置文件是 eslint.config.js！
TypeError: ... is not iterable (不是可迭代对象)
- 真相：在新的 eslint.config.js 中，插件的配置方式也变了。比如，eslint-plugin-vue 的推荐配置，需要从 ...pluginVue.configs["vue3-recommended"] 改为 ...pluginVue.configs["flat/recommended"]。

在经历了一系列的“打怪升级”后，我们终于得到了这份与 ESLint v9+ 完美兼容的最终配置。

🛠️ 终极配置：三步搞定

步骤 1：安装“立法机构” (安装 npm 包)

首先，确保你的 package.json 中，devDependencies 包含了这些最新版本的“神器”：

"devDependencies": {
  "@typescript-eslint/eslint-plugin": "^8.x",
  "@typescript-eslint/parser": "^8.x",
  "eslint": "^9.x",
  "eslint-plugin-vue": "^10.x",
  "globals": "^15.x",
  "typescript": "^5.x",
  "typescript-eslint": "^8.x",
  ...
}

如果缺失，请通过 npm install --save-dev <package-name> 安装。

步骤 2：颁布“法典” (创建 `eslint.config.js`)

在你的项目根目录下，删除所有旧的 .eslintrc.js 和 .eslintignore 文件，然后创建一个全新的 eslint.config.js 文件，并填入以下内容：

// eslint.config.js
import globals from "globals";
import pluginJs from "@eslint/js";
import tseslint from "typescript-eslint";
import pluginVue from "eslint-plugin-vue";

export default [
  // 1. 全局配置
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      parser: pluginVue.parser, // 👈 使用 pluginVue 提供的解析器
      parserOptions: {
        parser: tseslint.parser, // 👈 在 <script> 块中使用 TS 解析器
        sourceType: "module",
      },
    },
  },

  // 2. 启用推荐的规则集
  pluginJs.configs.recommended,
  ...tseslint.configs.recommended,
  ...pluginVue.configs["flat/recommended"], // 👈 使用 flat/recommended

  // 3. 自定义规则
  {
    rules: {
      "@typescript-eslint/no-unused-vars": "error",
      "@typescript-eslint/no-explicit-any": "off",
      "vue/multi-word-component-names": "off",
      "vue/max-attributes-per-line": "off",
      "vue/singleline-html-element-content-newline": "off",
      "no-console": process.env.NODE_ENV === 'production' ? 'warn' : 'off',
      "no-debugger": process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    },
  },

  // 4. 忽略文件配置 (替代 .eslintignore)
  {
    ignores: [
      "node_modules/",
      "dist/",
      ".vite/",
      ".vscode/",
      "public/",
      "*.md",
      "*.config.js",
      "*.config.ts",
    ],
  },
];

步骤 3：为 VSCode 请来“警察” (安装插件)

这是让魔法在你的编辑器里生效的最关键一步！

打开 VSCode，进入“扩展”面板。
搜索并安装由 Microsoft 发布的 ESLint 插件。
（重要！） 安装完成后，完全关闭并重新打开 VSCode。

🤔 一个新问题：我们还需要 `vite-plugin-eslint` 吗？

在旧的配置中，我们通常会在 vite.config.ts 中加入 vite-plugin-eslint，以便在 npm run dev 的终端里看到 ESLint 报错。

但在 ESLint v9+ 的时代，这不再是必需的了！

原因：最新版的 VSCode ESLint 插件，其后台服务已经足够强大和实时。它独立于 Vite 运行，能立即在你的编辑器里给出反馈。
重复工作：保留 vite-plugin-eslint 会导致重复检查，并可能轻微拖慢 Vite 的热更新 (HMR, Hot Module Replacement) 速度。
最佳实践：依赖“IDE (Integrated Development Environment, 集成开发环境) 实时检查” + “Git 提交前检查 (lint-staged)” + “CI/CD (Continuous Integration/Continuous Deployment, 持续集成/持续部署) 流程检查”这三道防线，是更现代化的做法。

结论：你可以安全地从 vite.config.ts 和 package.json 中移除 vite-plugin-eslint，让你的配置更简洁。

✨ 见证奇迹：享受“实时纠错”的开发体验

完成以上所有配置后，你的开发流程将焕然一新：

实时红线 🚨：任何 TS 错误或不规范的写法，都会被立即标记。
清晰提示 💡：鼠标悬浮即可看到详细的错误说明。
构建拦截 🛑：npm run build 会因为 ESLint 错误而中止，确保你不会将有问题的代码发布出去。

总结与反思 🎓

这次的配置之旅，让我们学到了：

💡 警惕“破坏性更新”：工具链的主版本升级（如 ESLint v8 -> v9），往往意味着配置文件的彻底变革。
💡 拥抱 “flat config”：eslint.config.js 是未来的趋势，它更灵活、更强大。
💡 简化你的工具链：随着 IDE 和核心工具的进化，一些辅助插件（如 vite-plugin-eslint）的历史使命可能已经完成，适时地移除它们，可以让你的项目更轻量。

希望这次的“踩坑”与“填坑”经历能对你有所帮助！现在，去享受这个“被迫”写出高质量代码的清爽过程吧！

Happy Linting! 💻✨

ESLint v9+ 配置总结 📋

方面	核心内容	关键点 & 亮点 ✨
问题 ❓	ESLint v9+ 配置复杂，旧的 `.eslintrc` 文件失效，导致 `Could not find config file` 错误。	版本升级引发的“血案” 🩸
解决方案 🛠️	采用全新的 “flat config” 格式，即 `eslint.config.js` 文件。	拥抱未来，告别过去 👋
关键依赖 📦	`eslint@^9`, `typescript-eslint@^8`, `eslint-plugin-vue@^10`, `globals`	生态系统同步升级 🔄
核心配置 🔑	`import` 语法, `export default [...]` 数组, `ignores` 属性	模块化、扁平化、更清晰 🎨
IDE 集成 🔌	安装 VSCode ESLint 插件，并重启 VSCode。	实时反馈的“警察” 👮‍♂️
Vite 集成 🚀	不再需要 `vite-plugin-eslint`，可以移除。	简化工具链，提升 HMR 速度 ✅

图解工作流程 📊

流程图：从编码到构建的全程守护

时序图：VSCode 插件的实时交互

状态图：代码文件的质量状态

类图：`eslint.config.js` 的结构抽象

实体关系图：工具链的依赖关系

思维导图：ESLint v9+ 配置全景解析

Vue 3 + Vite 项目 ESLint v9+ 终极配置指南
- 目标：实现代码质量全流程保障
  - 编码时：IDE 实时反馈
  - 提交时：Git 钩子拦截
  - 构建时：打包命令中止
- 核心变革：ESLint v9+ 引入 “flat config”
  - 旧配置 (eslintrc)
    - 文件名：.eslintrc.js / .eslintrc.json
    - 忽略文件：.eslintignore
    - 状态：已被废弃 ❌
  - 新配置 (flat config)
    - 文件名：eslint.config.js
    - 忽略文件：在 eslint.config.js 内部使用 ignores 属性
    - 状态：当前最佳实践 ✅
- 配置步骤
  - 第一步：安装依赖 (npm)
    - eslint@^9
    - typescript-eslint@^8 (新的统一包)
    - eslint-plugin-vue@^10
    - globals
  - 第二步：创建 eslint.config.js
    - 删除所有旧的 .eslintrc 和 .eslintignore 文件
    - 使用 import / export default 语法
    - 配置结构是一个数组
    - 关键配置项
      - languageOptions: 定义解析器 (pluginVue.parser) 和全局变量
      - extends: 使用 ...plugin.configs.recommended 形式展开
      - rules: 自定义或覆盖规则
      - ignores: 定义要忽略的文件和目录
  - 第三步：配置 VSCode
    - 安装 Microsoft 官方的 ESLint 插件
    - 重启 VSCode
- 工具链演进
  - vite-plugin-eslint
    - 作用：在 npm run dev 终端中显示 ESLint 错误
    - 现状：在 ESLint v9 + 强大的 VSCode 插件组合下，已不再是必需品，可以移除以简化配置和提升 HMR 速度。