在开发 Vue 3 项目时，频繁地手动 import { ref, reactive } from 'vue' 以及引入 UI 组件库的按需加载代码，往往会让人感到繁琐。为了提升开发效率，社区提供了两个神器：unplugin-auto-import 和 unplugin-vue-components。
本文将详细记录如何在 Vite + Vue 3 项目中，完美集成 Ant Design Vue 4.x 的自动导入功能，并避开 TypeScript 类型声明和 CSS-in-JS 样式加载的常见踩坑点。
1. 安装核心依赖
这两个插件属于构建阶段的工具，因此需要作为开发依赖（devDependencies）安装。
打开终端，在项目根目录运行以下命令：
npm install -D unplugin-auto-import unplugin-vue-components
2. 配置 vite.config.ts
安装完成后，需要在 Vite 的配置文件中注册这两个插件，并引入对应的 UI 库解析器（Resolver）。以下是完整的配置代码：
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'
// 1. 引入自动导入插件核心
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
// 2. 引入 Ant Design Vue 的解析器
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'
export default defineConfig({
plugins: [
vue(),
// 自动导入 Vue API (如 ref, watch, useRouter 等)
AutoImport({
imports: ['vue', 'vue-router'],
// 【关键技巧】将自动生成的类型声明文件放到 src 目录下
dts: 'src/auto-imports.d.ts',
}),
// 自动导入 Vue 组件 (如 <a-button>)
Components({
resolvers: [
AntDesignVueResolver({
// 【避坑指南】Ant Design Vue 4.x 已全面拥抱 CSS-in-JS
// 这里必须设置为 false，否则启动会报错找不到 less/css 样式文件
importStyle: false,
})
],
// 【关键技巧】将自动生成的类型声明文件放到 src 目录下
dts: 'src/components.d.ts',
}),
],
resolve: {
alias: {
'@': fileURLToPath(new URL('./src', import.meta.url)),
},
},
})
3. 核心配置原理解析与避坑指南
配置看似简单，但有几个细节如果不注意，极容易在项目初期卡壳：
💡 避坑一：为什么 importStyle 必须为 false？
如果你使用的是 Ant Design Vue 4.x 版本，该版本已经全面改用 CSS-in-JS 技术。这意味着组件自带样式，不再需要像 3.x 版本那样额外去加载 .less 或 .css 文件。如果保留默认的样式导入配置，Vite 在打包时会因为找不到对应的样式文件而报错。
💡 避坑二：为什么要把 .d.ts 生成在 src/ 目录下？
默认情况下（设置 dts: true 时），插件会把生成的 auto-imports.d.ts 和 components.d.ts 放在项目根目录。 但是，现代 Vue 项目的 tsconfig.app.json 中通常配置了 "include": ["src/**/*"]，这意味着 TypeScript 编译器只扫描 src 目录。如果文件在根目录，编辑器就会因为找不到类型而对 ref 或 <a-button> 疯狂标红报错。将生成路径指定为 src/xxx.d.ts，天生完美契合 TypeScript 的扫描范围，真正做到零额外配置。
💡 疑惑解答：为什么官网找不到 AntDesignVueResolver？
很多新手去 Ant Design Vue 官网搜不到这个解析器，这是因为该解析器并非官方团队维护，而是 unplugin-vue-components 插件内置提供的适配器代码。这是整个 Vue 社区目前最标准、最主流的自动导入方案，放心使用即可。
4. 运行与验证
配置保存完毕后，杀掉原本的终端进程，重新运行开发环境：
npm run dev
启动的瞬间，Vite 会自动扫描项目，并在你的 src/ 目录下生成 auto-imports.d.ts 和 components.d.ts 两个文件。
此时，你可以直接在组件中使用，无需写任何 import 语句：
代码段
<template>
<div>
<!-- 直接使用组件 -->
<a-button type="primary" @click="count++">
点击次数：{{ count }}
</a-button>
</div>
</template>
<script setup lang="ts">
// 直接使用 ref，无需 import { ref } from 'vue'
const count = ref(0)
</script>
至此，项目的自动导入配置彻底完成，既保持了代码的清爽，又保留了完整的 TypeScript 类型提示。