在 vue3 通用模板的搭建系列中，我们已经实现了页面自动注册和布局统一管理，但开发中仍有两个高频痛点：使用 ref、computed 等 api 时需手动导入，使用自定义组件时也必须先引入再注册。这些重复的机械操作不仅拖慢开发速度，还容易因遗漏导入出现报错。

今天就为大家带来两款 Vue3 生态的高效插件——unplugin-auto-import 和 unplugin-vue-components，通过简单配置实现 API 和组件的自动导入，彻底告别繁琐的 import 语句，让代码更简洁、开发更高效！

一、unplugin-auto-import：API 自动导入，告别重复引入

unplugin-auto-import 是一款星标 3.8k + 的优秀开源插件，支持 Vue、Vue Router、Pinia 等主流库的 API 自动导入。集成后，在组件中可直接使用相关 API，无需手动编写导入代码，大幅提升开发体验。
GitHub 地址：https://github.com/unplugin/unplugin-auto-import

1. 安装依赖

作为开发依赖安装，当前最新版本 20.3.0：

pnpm add unplugin-auto-import -D

2. Vite 配置集成

在 vite.config.ts 中引入并配置插件。由于我们已集成 unplugin-vue-router 实现自动路由，需将路由导入替换为 VueRouterAutoImports，同时指定需要自动导入的文件类型：

// ...
import AutoImport from 'unplugin-auto-import/vite'
import { VueRouterAutoImports } from 'unplugin-vue-router'

export default defineConfig({
  plugins: [
    // ...其他插件
    AutoImport({
      // 指定需要自动导入的文件格式
      include: [
        /\.([tj]sx?)$/, // .ts, .tsx, .js, .jsx
        /\.vue$/,
        /\.vue\?vue/,
        /\.md$/
      ],
      // 配置自动导入的库
      imports: ['vue', VueRouterAutoImports, 'pinia']
    }),
  ],
  // ...
})

3. 配置 TypeScript 类型声明

重启项目后，插件会在项目根目录自动生成类型声明文件 auto-imports.d.ts。为了让 TypeScript 识别该文件，需在 tsconfig.app.json 的 include 中添加：

{
  // ...其他配置
  "include": [
    // ...原有文件
    "auto-imports.d.ts"
  ]
}

4. 扩展集成 VueUse，简化功能开发

配置完成后，Vue、Vue Router、Pinia 的 API 已可直接使用，比如 ref、useRoute、defineStore 等，无需再写 import 语句。

<template>
  <div>{{ msg }}</div>
</template>

<script setup lang="ts">
// 无需 import { ref } from 'vue'
const msg = ref('Hello Vue3 AutoImport!')
</script>

如果需要扩展其他库的自动导入，只需在 imports 数组中追加即可。这里推荐集成 Vue3 必备工具集 @vueuse/core（当前版本 14.1.0），它提供了大量实用的组合式 API，能大幅简化暗黑模式、状态管理等常见功能开发。

安装 VueUse：

pnpm add @vueuse/core

配置自动导入：

AutoImport({
  // ...其他配置
  imports: ['vue', VueRouterAutoImports, 'pinia', '@vueuse/core']
})

5. 实战：VueUse 实现暗黑模式一键切换

基于 VueUse 的 useDark 和 useToggle，可快速实现响应式 + 持久化的暗黑模式切换，无需手动操作 dom 和本地存储，代码极简且易维护：

<template>
  <div class="index">首页</div>
  <div>当前暗黑模式：{{ isDark }}</div>
  <button @click="toggleDark()">切换主题</button>
</template>

<script setup lang="ts">
const msg = ref('Hello VueUse!')
// 无需导入，直接使用
const isDark = useDark({
  selector: 'html',
  attribute: '>,
  valueDark: 'dark',
  valueLight: 'light'
})
const toggleDark = useToggle(isDark)
</script>

useDark 会自动持久化主题状态，页面刷新后仍保持当前设置，相比原生 DOM 操作更优雅、更稳定。

二、unplugin-vue-components：组件自动注册，按需加载无压力

解决了 API 自动导入问题，组件的手动导入仍会影响开发效率——比如使用自定义的 Icon 组件，每次都要写 import Icon from '@/components/icon/icon.vue'，组件数量增多时尤为繁琐。

unplugin-vue-components 正是为解决此问题而生，星标 4.2k+，支持 src/components 目录下组件的自动扫描和注册，无需手动全局注册或局部导入，真正实现创建即使用。
GitHub 地址：https://github.com/unplugin/unplugin-vue-components

1. 安装依赖

开发依赖安装，当前最新版本 30.0.0：

pnpm add unplugin-vue-components -D

2. Vite 基础配置

在 vite.config.ts 中引入并配置，默认开启深度扫描，自动注册 src/components 及子目录下的所有组件：

// ...
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  plugins: [
    // ...其他插件
    Components({
      deep: true, // 深度扫描子目录
      directoryAsNamespace: false // 不启用文件夹命名空间
    })
  ],
  // ...
})

插件支持命名空间、指令自动导入、第三方 UI 库解析等高级功能。例如设置 directoryAsNamespace: true 时，可基于文件夹结构为组件添加命名空间，适合大型项目的组件分类管理。

3. 配置 TypeScript 类型声明

重启项目后，插件自动生成组件类型声明文件 components.d.ts，将其添加到 tsconfig.app.json 的 include 中，保证 TypeScript 类型提示正常：

{
  // ...其他配置
  "include": [
    // ...原有文件
    "auto-imports.d.ts",
    "components.d.ts"
  ]
}

4. 实战：组件直接使用，无需导入

配置完成后，src/components 下的所有组件均可在模板中直接使用。比如自定义 Icon 组件，无需任何导入代码，直接在页面中写 <Icon /> 即可，浏览器控制台也不会再出现 Failed to resolve component 的警告。

这种方式实现了组件的按需自动注册——插件只会扫描并注册项目中实际使用的组件，不会造成打包体积冗余，兼顾开发效率和打包性能。

三、核心优势：让开发回归业务本身

通过 unplugin-auto-import 和 unplugin-vue-components 的组合配置，我们的 Vue3 项目实现了两大核心优化，开发效率大幅提升：

• API 零导入：Vue、Vue Router、Pinia、VueUse 的所有 API 直接使用，告别满屏的 import 语句，代码更简洁；

• 组件零注册：自定义组件创建即使用，无需手动局部导入或全局注册，减少机械操作；

• 类型全支持：自动生成类型声明文件，保证 TypeScript 的类型提示和语法校验，开发更规范；

• 按需加载：组件仅注册实际使用的部分，避免打包体积过大，兼顾性能；

• 扩展灵活：支持第三方库、自定义指令的自动导入，可根据项目需求灵活配置。

简单来说，这两款插件让我们从重复的导入、注册操作中解放出来，将更多精力放在业务逻辑开发和用户体验优化上。这也是现代前端开发的核心追求——让工具服务于开发，而非拖累开发。

四、后续规划：通用模板再升级

本次的自动导入和组件自动注册配置，让 Vue3 通用模板的开发体验更上一层楼，这也是我个人使用最久的模板版本。但在实际项目开发中，国际化 i18n 和打包构建优化是两个高频需求：

• 国际化 i18n：支撑多语言项目开发，实现文案的统一管理和快速切换；

• 打包构建优化：通过分包、压缩、按需加载等方式，减小打包体积，提升项目加载速度。

考虑将这两个功能集成到通用模板中，让模板的实用性和通用性更强。大家是否需要我详细讲解这两个功能的集成方案？欢迎在留言区或私信告诉我你的意见，你的建议会直接决定后续的更新方向。

写在最后

优秀的开源工具是提升开发效率的关键，unplugin-auto-import 和 unplugin-vue-components 作为 Vue3 生态的必备插件，配置简单却能带来质的开发体验提升。

同时也建议大家养成阅读官方文档的习惯，插件的更多高级配置和避坑技巧，都能在官方 README 和 issues 中找到答案——这也是成为一名合格前端开发者的基本能力。

本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！

链接: https://fly63.com/article/detial/13460