写 Vue3 项目的时候最烦的其实不是业务逻辑而是每个文件开头那一坨 import。写个 ref 要 import用个 computed 要 import写个 ElMessage 还要 import一套页面写下来光 import 就占了十几行。后来我在一个后台管理系统里用 Vite Vue3 TypeScript 重构实在受不了这种重复劳动就把 unplugin-auto-import 和 unplugin-vue-components 配上了。结果爽是真爽Eslint 报错也是真的多尤其是ref is not defined这种 no-undef 红波浪线满屏都是。这篇文章就专门聊清楚两件事怎么把 Vite Vue3 TS 项目里的自动引入配置好以及怎么把配套的 Eslint 报错彻底解决掉。里面全是实际项目踩过坑之后留下的配置和思路适合正在做 Vue3 后台管理系统、或者刚用 Vite 搭建项目被各种 TS 和 Eslint 问题折磨的朋友。1. 先从项目地基说起Vite Vue3 TS 怎么搭1.1 三件套选型背后的取舍现在的 Vue3 项目脚手架的默认选项基本就是 Vite TypeScript。之前很多人纠结 Vue3 用 TS 好还是 JS 好我的看法是如果项目超过三个页面、两个人协作直接上 TS后期重构和接手成本会低很多。Vite 的开发服务器启动速度快到离谱尤其相比 Webpack 那套热更新几乎是秒开这也是 Vue3 项目现在普遍选 Vite 而不是 Webpack 的真实原因。建项目的命令没什么好说的我就是用官方脚手架npm create vitelatest my-admin -- --template vue-ts这个模板会直接把 Vue3 Vite TS 配好省事。不过光靠模板还不够一个正经的后台管理系统还需要 router、pinia、eslint、prettier 这些基础设施后面我会一起串起来说。1.2 为什么把自动引入放在配置优先级前列团队里写 Vue3 组合式 API 的同学应该都有感受ref、reactive、computed、watch、onMounted这些 API 几乎每个组件都要用到。如果每写一个组件都要重复 import那这个过程本身就是在浪费生命。自动引入的思路很简单就是借助 Vite 插件在编译阶段做静态分析把你用到的 API 或者组件在构建时自动注入到模块里开发者只需要在代码里直接用不用手动写 import。这样做有三个明显好处代码更干净组件的script setup部分专注于逻辑而不是 import 堆砌。重构时移动文件不用再改 import 路径尤其是 alias 配了之后少了很多低级报错。新增项目成员时的上手成本低新人不用关心这个函数从哪来。当然也有争议比如代码可读性会不会变差、编辑器跳转会不会失效。这些确实存在但通过配置dts生成类型声明文件、配合 Eslint 的 globals 配置基本可以消解掉。后面我全部展开讲。2. unplugin-auto-import 配置拆解2.1 先装依赖注意版本别踩坑自动引入主要靠两个插件一个是处理 API 和函数的 unplugin-auto-import另一个是处理 Vue 单文件组件里组件自动注册的 unplugin-vue-components。两者通常是搭配使用因为它们解决的问题重叠但侧重点不同前者管函数和变量后者管组件。我安装时的命令npm install -D unplugin-auto-import unplugin-vue-components这里有个小经验装完以后看一眼 package.json 里的版本号然后去 GitHub 确认当前版本支持的 Vite 版本。比如 unplugin 系列的插件早期版本对 Vite 5 的支持是靠后更新才完善的如果你用的是 Vite 5 或更高版本尽量选最新版避免出现插件静默失效的问题。2.2 核心配置auto-import 里的关键参数插件装好后在vite.config.ts里做配置。下面这套是我现在一直在用的基础版import { defineConfig } from vite import vue from vitejs/plugin-vue import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), AutoImport({ imports: [vue, vue-router, pinia], resolvers: [ElementPlusResolver()], dts: src/auto-imports.d.ts, eslintrc: { enabled: true, filepath: ./.eslintrc-auto-import.json, globalsPropValue: true, }, }), Components({ resolvers: [ElementPlusResolver()], dts: src/components.d.ts, }), ], })逐个解释一下这些配置项imports这里写的vue、vue-router、pinia意思是要自动引入这些库导出的 API。比如ref、computed、watch、useRoute、useRouter、storeToRefs这些都不用再手动 import。resolvers这里挂上 ElementPlusResolver目的是让 unplugin-auto-import 在检测到ElMessage、ElNotification这类 API 时自动引入对应的样式和函数。这个和 Vant、Ant Design Vue 的用法类似组件库不同选对应的 resolver 就行。dts自动生成类型声明文件的路径。这个文件很重要TS 编译和编辑器智能提示全靠它。eslintrc.enabled让插件生成一个 Eslint 可用的 globals 配置文件这是解决 no-undef 报错的关键钥匙后面专门讲。globalsPropValue生成的 globals 是用true还是readonly一般写true就行。2.3 组件自动引入unplugin-vue-components 联动把Components插件也配进plugins数组后组件也不需要 import 了。比如页面里直接用div classdemoel-button typeprimary按钮/el-button/div插件会自动把ElButton和它的样式引进来不需要你在script里写import ElButton from element-plus。组件和 API 自动引入看起来是两套机制但它们配合起来才能做到写 Vue3 就像不用管导入这件事。我见过不少人只配了 AutoImport 没配 Components或者反过来结果仍然有一半的 import 要手动写体验打了折扣。配置生成的文件默认路径分别是src/auto-imports.d.ts和src/components.d.ts这两个文件建议提交到 git 仓库。团队里其他同事拉代码时编辑器能直接识别类型不至于每个人都要跑一遍 dev 才能正常提示。3. Eslint 报错排查与解决3.1 常见报错现场还原自动引入配置好后第一件让人崩溃的事情就是 Eslint 开始满屏报错。我当时遇到的最典型场景是在script setup里直接用了ref(0)没有 importref。在事件处理里用了ElMessage.success(保存成功)。在路由文件里用了createRouter没有 import。Eslint 立刻给出ref is not defined、ElMessage is not defined这类 no-undef 错误。为什么因为 Eslint 做静态检查时它读的只有你写的源码不会知道 Vite 编译时帮你做了什么注入。它看到你使用了一个当前文件里没声明、没 import、也没从全局变量表里查到的变量自然就报未定义。反过来想要解决这个问题不复杂方案是告诉 Eslint这些变量是全局存在的别给我报错。 具体途径就是在 eslint 配置文件里补充globals。3.2 传统 .eslintrc.cjs 方案怎么配如果你用的是 ESLint 8 及以下的传统配置方式也就是.eslintrc.cjs这种老格式可以通过 unplugin-auto-import 自动生成 globals 文件来省掉手动维护的麻烦。上面 vite.config.ts 里eslintrc.enabled: true的那段配置启动项目之后会在项目根目录生成一个.eslintrc-auto-import.json文件。然后把.eslintrc.cjs里加上这样一段module.exports { extends: [ plugin:vue/vue3-recommended, plugin:typescript-eslint/recommended, ./.eslintrc-auto-import.json, ], }注意extends数组里塞入生成的 json 文件路径这会让 Eslint 把所有自动引入的 API 看成本地全局变量ref is not defined这类报错就会消失。这段配置也有一个细节值得注意globalsPropValue: true表示生成的 globals 里全部标记为可写变量。如果你希望更严格一些可以设置成readonly防止代码里对全局导入做赋值。但实际项目中true用的更多因为部分插件生成的变量确实可能被动态调用。3.3 ESLint 9 flat config 的配置姿势如果你的项目用的是新版 ESLint 9配置文件变成了eslint.config.js传统的.eslintrc.cjs已经不被支持了。这个时候不能再用extends旧语法得换成 globals 对象方式的配置。我用的是这种写法import autoImportGlobals from ./.eslintrc-auto-import.json export default [ { files: [**/*.{js,mjs,cjs,ts,vue}], languageOptions: { globals: { ...autoImportGlobals.globals, }, }, }, ]autoImportGlobals本质上就是 JSON 里的{ globals: { ref: true, ... } }把它展开进 flat config 的languageOptions.globals就行。还有一个更省事的方式在 unplugin 新版本里支持把生成的 globals 写到.eslintrc-auto-import.json然后再在eslint.config.js里引入原理一样只是路径要写对。我这里就把文件生成在项目根目录避免和src混在一起。3.4 宏和指令类警告的额外处理除了 no-undefVue3 项目里还经常遇到两类问题一类是defineProps、defineEmits、withDefaults这些编译器宏。它们在编译阶段由 Vue 处理Eslint 默认是不认识它们的会报defineProps is not defined。解决方法是安装 eslint-plugin-vue 后在插件配置里开启 vue3 推荐规则集推荐规则集里已经把vue/no-undef-components和这些编译器宏的豁免规则包含进去了。检查一下你的 extends 里有没有plugin:vue/vue3-recommended没有就补上。另一类是 HTML 模板里的注释指令比如!-- eslint-disable-next-line --在template里报v-for相关警告。这种一般是vue/comment-directive规则没配置好在规则里把vue/comment-directive设为error或者warn即可新版 plugin 通常默认已处理好。4. 自动配置后的连锁问题排查实录4.1 配置没生效先查缓存和重启顺序我踩过的最常见的坑是改了vite.config.ts后刷新页面结果自动引入还是没生效Eslint 的报错也还在。原因其实不难猜Vite 的依赖预构建和插件缓存。解决套路有三个改完 vite.config.ts 必须重启 dev server纯粹刷新页面不够。如果 node_modules/.vite 里有缓存问题直接删掉再重启强制重新预构建。检查项目根目录下的 tsconfig.json 是否在 include 里覆盖了src确保自动生成的src/auto-imports.d.ts能被 TS 编译器读到。如果 include 写的是[src/**/*.ts, src/**/*.d.ts, src/**/*.vue]那生成的 d.ts 在 src 下没有问题如果生成路径在项目根目录就要手动加进去。4.2 TS 类型报错与 dts 文件管理自动引入在 TS 项目里最容易出的问题不是运行时报错而是类型不识别。明明ref已经在组件里用了TS 却提示找不到名称ref。这个就是因为 TS 没有把 auto-import 生成的声明文件纳入编译上下文。处理方式分两步第一确认vite.config.ts里的dts路径和 tsconfig.json 的 include 匹配。比如我设置的是dts: src/auto-imports.d.ts那么在 tsconfig.json 里就要保证 include 覆盖src目录下的.d.ts文件。第二有些场景下src/components.d.ts和src/auto-imports.d.ts会被gitignore掉导致别人克隆项目后编辑器不识别。我的建议是这两个文件不要 ignore直接提交到仓库。它们看起来是自动生成的但体积小而且提交了以后能确保团队所有成员的 TS 提示和 Eslint 状态一致。4.3 自动导入和手动导入冲突怎么办有人会问自动引入配好之后我在组件里又手动 import 了一遍ref会不会冲突答案是不会因为同名的函数手动 import 的优先级实际上更高编译后不会出现重复声明。而且编辑器也能正确解析只是手动 import 这行代码变得多余了。但如果这种冗余一直存在代码风格会变得混乱。团队里可以约定一个不手动导入由插件管理的 API的规范。具体执行可以通过 Eslint 规则或者 Code Review 来控制。如果你用no-restricted-imports可以把自动引入的模块来源写进规则的 paths 里谁手动 import 了就直接报错。5. 结合 Pinia、Router、Vitest 的完整工程化配置5.1 把 API、组件、工具函数都纳入自动引入项目跑通之后我趁着热乎劲儿把 API 和工具函数也纳入了自动引入。unplugin-auto-import 支持自定义自动导入对象配置项imports里可以传函数对象比如AutoImport({ imports: [ vue, vue-router, pinia, { vueuse/core: [ useDebounceFn, useLocalStorage, ], /utils/request: [[default, request]], }, ], })这里的意思是从vueuse/core里解构出来的useDebounceFn、useLocalStorage可以直接用不需要 import。自己项目里的request工具也是这样。不过我要提醒一句自定义工具函数尽量少这么做因为工具函数一旦被自动引入项目里到处都能直接用但是如果哪天有人改了函数签名所有用到的地方都会在编译时才暴露问题排查起来比显式 import 要费劲。5.2 自动引入在单元测试中的坑如果你配了 Vitest 做单元测试自动引入的 API 在测试文件里是默认不可用的。因为 Vitest 默认不带 Vite 的插件列表需要把 vite.config.ts 里的 plugins 显式传递到 Vitest 配置里。我用的是 vitest.config.ts 里加mergeConfig的方式import { mergeConfig } from vite import vitestConfig from ./vitest.config export default mergeConfig( vitestConfig, { test: { environment: jsdom, }, }, )这里有点绕更直接的做法是直接把AutoImport和Components这两个插件在 vitest 配置里也启用否则测试文件里用ref、computed也会报错或者运行时挂掉。这个坑不踩一次很难注意网上相关的内容也不多。5.3 我最终落地的一套完整配置最后把我在后台管理系统里最终使用的一套版本号参考给你方便复现Vite:^5.0.0Vue:^3.4.0TypeScript:^5.2.0unplugin-auto-import:^0.17.0unplugin-vue-components:^0.26.0Element Plus:^2.5.0ESLint:^8.56.0eslint-plugin-vue:^9.20.0Vitest:^1.0.0这个组合目前在我本地跑得很稳热更新时间基本没变化也没有出现组件重复注册或样式加载错乱的情况。6. 项目自动化提升与后续扩展自动引入这步做完项目里还有一些小地方可以顺手优化。比如 new 一个数组时用的Array.from、判断类型用的typeof这些 JS 全局变量不存在 no-undef 问题不需要额外处理。容易被忽略的是 Pinia 组合式写法里常用的storeToRefs它属于 pinia 的导出所以要在imports里加上pinia否则会一直报错。再往后扩展可以考虑接入 Typed Router路由表类型推导、用 unplugin-icons 自动按需引入图标组件。它们和自动引入的理念一致都是用的时候直接引不用管导入组合在一起Vue3 项目的开发体验能再上一个台阶。配置自动引入的真正难点不在于安装插件而在于理解它和 Lint、TS 编译器之间的协作方式。只要想明白编译时自动注入和静态检查需要显式声明这两者之间的差异遇到报错自然就能根据不同工具的职责对症下药。