Vue 3 + Vite 自动引入插件完整指南(unplugin-vue-components,unplugin-auto-import)

2026年3月6日 10:33

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`

效果对比

使用前（手动导入）：

<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>

使用后（自动导入）：

<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 安装依赖

npm install -D unplugin-vue-components unplugin-auto-import

如果需要自动导入 Element Plus 等 UI 框架的组件和样式，不需要额外安装 resolver，它们已内置在 unplugin-vue-components 中。

2.2 配置 `vite.config.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 能识别自动生成的类型文件：

{
  "compilerOptions": {
    // ... 其他配置
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.vue",
    "src/types/auto-imports.d.ts",
    "src/types/components.d.ts"
  ]
}

2.4 配置 ESLint（可选）

在 .eslintrc.cjs 中引入自动生成的全局变量声明：

module.exports = {
  extends: [
    // ... 其他配置
    "./.eslintrc-auto-import.json", // 自动导入的全局变量
  ],
};

三、组件目录结构

unplugin-vue-components 支持以下两种组件结构，组件名自动推导：

src/components/
│
├── MyButton.vue              → 组件名：<MyButton />
│
├── DictTag/
│   └── index.vue             → 组件名：<DictTag />
│
├── UserCard/
│   └── index.vue             → 组件名：<UserCard />
│
└── FileUpload/
    └── index.vue             → 组件名：<FileUpload />

四、自动生成的文件说明

启动项目后，插件会自动生成以下文件（不要手动修改，也建议加入 .gitignore）：

`src/types/components.d.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 类型声明）

// 由 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 按需导入

npm install element-plus

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 自定义导入规则

AutoImport({
  imports: [
    "vue",
    "vue-router",
    {
      // 自定义导入：从 '@/utils/request' 自动导入 request 函数
      "@/utils/request": ["request", "download"],
      // 从 axios 自动导入
      axios: [["default", "axios"]],
    },
  ],
});

5.3 排除不需要自动注册的组件

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 文件路径。

七、工作原理简述

┌──────────────────────────────────────────────────┐
│                   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。

阅读视图