Vue 3 + Vite 自动引入插件完整指南
介绍如何在 Vue 3 + Vite 项目中配置
unplugin-vue-components（自动引入组件）和unplugin-auto-import（自动引入 API），实现零 import 开发体验。
一、两个插件的区别
unplugin-vue-components |
unplugin-auto-import |
|
|---|---|---|
| 作用 | 自动导入组件 | 自动导入 API / 函数 |
| 省去什么 | import DictTag from '@/components/DictTag/index.vue' |
import { ref, computed } from 'vue' |
| 生成的类型文件 | components.d.ts |
auto-imports.d.ts |
效果对比
使用前（手动导入）：
vue
<template>
<DictTag :value="count" />
</template>
<script setup>
import { ref, computed, onMounted } from "vue";
import { useRouter } from "vue-router";
import DictTag from "@/components/DictTag/index.vue";
const count = ref(0);
const doubled = computed(() => count.value * 2);
</script>使用后（自动导入）：
vue
<template>
<DictTag :value="count" />
<!-- 自动导入组件 -->
</template>
<script setup>
const count = ref(0); // 自动导入 ref
const doubled = computed(() => count.value * 2); // 自动导入 computed
const router = useRouter(); // 自动导入 useRouter
</script>二、从零搭建步骤
2.1 安装依赖
bash
npm install -D unplugin-vue-components unplugin-auto-import如果需要自动导入 Element Plus 等 UI 框架的组件和样式，不需要额外安装 resolver，它们已内置在
unplugin-vue-components中。
2.2 配置 vite.config.ts
ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import Components from "unplugin-vue-components/vite";
import AutoImport from "unplugin-auto-import/vite";
// 如需 Element Plus 按需导入，取消下面注释
// import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
export default defineConfig({
plugins: [
vue(),
// ==========================================
// 插件一：自动导入 API（ref、computed 等）
// ==========================================
AutoImport({
// 需要自动导入的库
imports: [
"vue", // ref, computed, watch, onMounted 等
"vue-router", // useRouter, useRoute 等
"pinia", // defineStore, storeToRefs 等
// '@vueuse/core', // 按需添加
],
// 生成类型声明文件（让编辑器识别自动导入的 API）
dts: "src/types/auto-imports.d.ts",
// 是否在 Vue 模板中自动导入
vueTemplate: true,
// 如需自动导入 Element Plus 的 API（ElMessage 等），取消注释：
// resolvers: [ElementPlusResolver()],
// 生成 ESLint 配置（避免 eslint 报未定义错误）
eslintrc: {
enabled: true, // 首次生成后可改为 false
filepath: "./.eslintrc-auto-import.json",
},
}),
// ==========================================
// 插件二：自动导入组件
// ==========================================
Components({
// 指定组件扫描目录
dirs: ["src/components"],
// 递归扫描子目录
deep: true,
// 组件文件扩展名
extensions: ["vue"],
// 生成类型声明文件
dts: "src/types/components.d.ts",
// 如需自动导入 Element Plus 组件，取消注释：
// resolvers: [ElementPlusResolver()],
}),
],
});2.3 配置 tsconfig.json
确保 TypeScript 能识别自动生成的类型文件：
json
{
"compilerOptions": {
// ... 其他配置
},
"include": [
"src/**/*.ts",
"src/**/*.vue",
"src/types/auto-imports.d.ts",
"src/types/components.d.ts"
]
}2.4 配置 ESLint（可选）
在 .eslintrc.cjs 中引入自动生成的全局变量声明：
js
module.exports = {
extends: [
// ... 其他配置
"./.eslintrc-auto-import.json", // 自动导入的全局变量
],
};三、组件目录结构
unplugin-vue-components 支持以下两种组件结构，组件名自动推导：
xml
src/components/
│
├── MyButton.vue → 组件名：<MyButton />
│
├── DictTag/
│ └── index.vue → 组件名：<DictTag />
│
├── UserCard/
│ └── index.vue → 组件名：<UserCard />
│
└── FileUpload/
└── index.vue → 组件名：<FileUpload />四、自动生成的文件说明
启动项目后，插件会自动生成以下文件（不要手动修改 ，也建议加入 .gitignore）：
src/types/components.d.ts（组件类型声明）
ts
// 由 unplugin-vue-components 自动生成
declare module "vue" {
export interface GlobalComponents {
DictTag: (typeof import("../components/DictTag/index.vue"))["default"];
FileUpload: (typeof import("../components/FileUpload/index.vue"))["default"];
// ... 其他组件
}
}src/types/auto-imports.d.ts（API 类型声明）
ts
// 由 unplugin-auto-import 自动生成
declare global {
const ref: (typeof import("vue"))["ref"];
const computed: (typeof import("vue"))["computed"];
const watch: (typeof import("vue"))["watch"];
const onMounted: (typeof import("vue"))["onMounted"];
const useRouter: (typeof import("vue-router"))["useRouter"];
// ... 其他 API
}五、常用进阶配置
5.1 搭配 Element Plus 按需导入
bash
npm install element-plus
ts
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";
AutoImport({
imports: ["vue", "vue-router"],
resolvers: [ElementPlusResolver()], // 自动导入 ElMessage, ElNotification 等
});
Components({
dirs: ["src/components"],
resolvers: [ElementPlusResolver()], // 自动导入 <el-button>, <el-input> 等
});5.2 自定义导入规则
ts
AutoImport({
imports: [
"vue",
"vue-router",
{
// 自定义导入：从 '@/utils/request' 自动导入 request 函数
"@/utils/request": ["request", "download"],
// 从 axios 自动导入
axios: [["default", "axios"]],
},
],
});5.3 排除不需要自动注册的组件
ts
Components({
dirs: ["src/components"],
// 排除特定目录
exclude: [/\.test\./, /node_modules/],
});六、常见问题排查
Q1：组件自动导入不生效？
| 检查项 | 解决方案 |
|---|---|
components.d.ts 为空 |
删除后重启 npm run dev，确保有页面访问触发编译 |
项目路径含特殊字符 ()[]{} |
重命名路径，去掉括号等 glob 特殊字符 |
| 组件结构不对 | 确保是 ComponentName/index.vue 或 ComponentName.vue |
dirs 路径错误 |
用绝对路径验证：dirs: [path.resolve(__dirname, 'src/components')] |
Q2：ESLint 报 ref is not defined？
确保：
AutoImport中eslintrc.enabled设为true生成配置文件.eslintrc.cjs中 extends 了.eslintrc-auto-import.json- 生成后可将
enabled改回false（避免每次启动都重写）
Q3：编辑器没有智能提示？
确保 tsconfig.json 的 include 中包含了两个 .d.ts 文件路径。
七、工作原理简述
xml
┌──────────────────────────────────────────────────┐
│ Vite 编译流程 │
├──────────────────────────────────────────────────┤
│ │
│ .vue 文件 → Vite 编译 │
│ │ │
│ ├── <template> 中发现 <DictTag /> │
│ │ └── unplugin-vue-components 介入 │
│ │ └── 自动注入: │
│ │ import DictTag from │
│ │ '@/components/DictTag/index.vue' │
│ │ │
│ ├── <script> 中发现 ref() │
│ │ └── unplugin-auto-import 介入 │
│ │ └── 自动注入: │
│ │ import { ref } from 'vue' │
│ │ │
│ └── 编译产物（已包含所有 import） │
│ │
└──────────────────────────────────────────────────┘核心点 ：两个插件都是在 Vite 编译阶段 介入的，它们不改变你的源码，而是在编译产物中自动注入需要的 import 语句。写代码时完全不需要手动 import。