vite中正确使用unplugin-auto-import实现自动引入vue相关依赖（支持Eslint v9）

前言

在日常的 Vue 项目开发中，我们常常需要手动从 vue 或 vue-router 等库中导入 ref、computed、onMounted 等 API。这不仅是一项重复性的劳动，也打断了我们编写业务逻辑的思路。

手动引入（之前）：

import { computed, ref } from 'vue'

const count = ref(0)
const doubled = computed(() => count.value * 2)

unplugin-auto-import 这款插件正是为了解决这个痛点而生。它能够自动为我们导入这些常用的 API，让我们专注于代码本身。

自动引入（之后）：

const count = ref(0)
const doubled = computed(() => count.value * 2)

对于想偷懒的人来说，还是挺不错的。

工作原理简介：

插件会在代码被vite或者其他框架处理的时候，解析生成的源码AST（抽象语法树），找到未被导入但是在配置中定义了的模块或变量，然后在源代码中插入对应的 import 语句来导入这些模块或变量。

当配置了dts: true的时候，还会在项目根目录生成auto-imports.d.ts的类型声明文件，我们需要在tsconfig.json文件中include加入该文件，这样在编辑器中，不import引入对应模块，也不会出现语法报错。

插件地址：unplugin-auto-import

安装：

npm i unplugin-auto-import -D

Vite + TypeScript 配置

1. 修改vite.config.ts：

// vite.config.ts
import AutoImport from "unplugin-auto-import/vite";

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ["vue", "vue-router"],
      dts: true
    }),
  ],
})

• imports: 此选项用于指定需要自动导入的预设库。插件内置了对 vue、vue-router、pinia 等流行库的支持。你可以在 插件仓库的 src/presets 目录 查看所有支持的预设。
  
• dts: 强烈建议设置为 true。它会为你生成类型声明文件。有些教程中会指定一个字符串路径（如 'src/auto-imports.d.ts')，这在你希望自定义文件位置时有用，但对于大多数项目，true 已经足够，它会在项目根目录生成 auto-imports.d.ts。

2. 更新tsconfig.json：

为了让 TypeScript 识别这些全局 API，需要将生成的 .d.ts 文件加入 include 数组。

{
"include": [
    "auto-imports.d.ts"
  ],
}

此时我们在vue组件中删除import引入的依赖，ts也不会报错了（如果没有生成这个d.ts文件，你需要先运行一下项目，让插件生成这个文件）。

ESLint 配置

自动导入解决了编码和类型检查的问题，但 ESLint 并不知道这些 API 是哪里来的，它会抛出 no-undef (未定义变量) 的错误。因此，我们需要让 ESLint 与 unplugin-auto-import 协同工作。

eslint v8.x版本及以下版本

这个官方文档已经给出教程了，在AutoImport插件的配置中启用eslintrc选项：

AutoImport({
  eslintrc: {
    enabled: true, // <-- this
  },
})

启动项目后（例如运行 npm run dev），插件会自动在根目录生成一个 .eslintrc-auto-import.json 文件。这个文件包含了所有自动导入 API 的全局变量声明。

接下来，只需在你的 ESLint 配置文件中 extends 这个生成的文件即可。

.eslintrc.js：

module.exports = {
  extends: [
    './.eslintrc-auto-import.json',
  ],
}

更多的配置可以参考官方文档：eslint-plugin-import

应对 ESLint v9+ 的新配置格式 (Flat Config)

ESLint v9 引入了全新的 "Flat Config" 配置格式（通常使用 eslint.config.js 或 eslint.config.ts），这使得旧的配置方式不再兼容。如果你使用的是最新版的 Vue 或脚手架，很可能已经遇到了这个问题。

之前我是直接让插件生成的文件设置成cjs文件格式，然后在eslint.config.cjs中引入这个配置，具体操作如下：

vit.config.ts：

AutoImport({
  eslintrc: {
    enabled: true, // <-- this
    filepath: "./.eslintrc-auto-import.cjs",
  },
})

.eslintrc.js：

import AutoImport from "./.eslintrc-auto-import.cjs";

export default [
  // 这里使用 AutoImport
 {
  ignores: [".vscode", "node_modules", "*.md", "*.woff", "*.ttf", ".idea", "dist", ".husky"],
  files: ["**/*.{js,ts,mjs,mts,cjs,cts,jsx,tsx,vue}"],
  languageOptions: {
   parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
    ecmaFeatures: {
     jsx: true
    }
   },
   globals: {
    ...AutoImport.globals
   }
  }
 },
  // 这里是自定义rules
 {
  rules: {
   "vue/multi-word-component-names": "off",
   "no-unused-vars": "off",
   "@typescript-eslint/no-explicit-any": "off",
   "@typescript-eslint/no-unused-vars": [
    "error",
    {
     args: "all",
     argsIgnorePattern: "^_",
     caughtErrors: "all",
     caughtErrorsIgnorePattern: "^_",
     destructuredArrayIgnorePattern: "^_",
     varsIgnorePattern: "^_",
     ignoreRestSiblings: true
    }
   ],
   "@typescript-eslint/no-unused-expressions": "off"
  }
 }
];

这种方式有点不够正确，加上最近我又去issues中翻了下，找到了这么一个内容：《How to correctly configure the json or js generated by eslintrc in eslint.config v9 version》

发现里面有人使用了一个插件：@eslint/eslintrc

了解了一下，这个插件是eslint官方出的一个插件，就是为了解决老版本迁移至v9版本的配置问题，它可以帮助我们将json或者js格式的eslint配置文件转换成v9版本的格式。

具体操作如下，首先我们将自动引入的配置还是使用.eslintrc-auto-import.json格式（这里删除了filepath属性）。

1. 保持 Vite 插件配置不变：

AutoImport({
  eslintrc: {
    enabled: true, // <-- this
  },
})

2. 安装兼容性工具：

npm i @eslint/eslintrc -D

@eslint/eslintrc 的作用是提供一个兼容层，让你可以在新的 Flat Config 中继续使用旧格式的配置文件。

3. 更新 ESLint 配置文件 (eslint.config.js 或 eslint.config.ts)：

我们可以将eslint.config.js调整为eslint.config.ts格式，这个格式在vue最新版的项目脚手架中已经成为了标准，应该是在为node默认支持ts文件做准备。

我以最新版的配置为例：

import { globalIgnores } from "eslint/config";
import { defineConfigWithVueTs, vueTsConfigs } from "@vue/eslint-config-typescript";
import pluginVue from "eslint-plugin-vue";
import pluginOxlint from "eslint-plugin-oxlint";
import skipFormatting from "@vue/eslint-config-prettier/skip-formatting";
import { FlatCompat } from "@eslint/eslintrc";

// To allow more languages other than `ts` in `.vue` files, uncomment the following lines:
// import { configureVueProject } from '@vue/eslint-config-typescript'
// configureVueProject({ scriptLangs: ['ts', 'tsx'] })
// More info at https://github.com/vuejs/eslint-config-typescript/#advanced-setup

const compat = new FlatCompat();

export default defineConfigWithVueTs(
 {
  name: "app/files-to-lint",
  files: ["**/*.{ts,mts,tsx,vue}"]
 },

 globalIgnores(["**/dist/**", "**/dist-ssr/**", "**/coverage/**"]),

 pluginVue.configs["flat/essential"],
 vueTsConfigs.recommended,
 ...pluginOxlint.configs["flat/recommended"],
  // 这里是自动引入的配置，我看人家也是写在 skipFormatting 前面，可能有什么特殊原因，不去深究了。
 ...compat.extends("./.eslintrc-auto-import.json"),
 skipFormatting,
  // 这里填写自定义rules
 {
  name: "app/files-to-lint",
  files: ["**/*.{ts,mts,tsx,vue}"],
  rules: {
   "vue/multi-word-component-names": "off",
   "no-unused-vars": "off",
   "@typescript-eslint/no-explicit-any": "off",
   "@typescript-eslint/no-unused-vars": [
    "error",
    {
     args: "all",
     argsIgnorePattern: "^_",
     caughtErrors: "all",
     caughtErrorsIgnorePattern: "^_",
     destructuredArrayIgnorePattern: "^_",
     varsIgnorePattern: "^_",
     ignoreRestSiblings: true
    }
   ],
   "@typescript-eslint/no-unused-expressions": "off"
  }
 },
 {
  name: "app/files-to-ignore",
  ignores: ["**/dist/**", "**/dist-ssr/**", "**/coverage/**"]
 }
);

核心步骤：

1. 从 @eslint/eslintrc 导入 FlatCompat。
2. 实例化 FlatCompat，它需要一个基础目录来解析相对路径。
3. 使用 ...compat.extends("./.eslintrc-auto-import.json") 将自动生成的配置“翻译”并集成到你的 Flat Config 数组中。

至此，你就拥有了一个与 Vite、TypeScript 和最新版 ESLint v9+ 完美集成的 unplugin-auto-import 配置。现在，你可以尽情享受无需手动 import 的编码乐趣了！