登录依赖自动导入：unplugin-auto-import 完整配置指南
unplugin-auto-import 完整配置指南
目录
简介
unplugin-auto-import 是一个 Vite/Webpack/Rollup 插件，用于自动导入 API，无需手动编写 import 语句。支持 Vue、Vue Router、Pinia 等库，以及自定义工具函数。
主要优势：
- ✅ 减少重复代码，无需手动导入
- ✅ 提升开发效率
- ✅ 支持 TypeScript 类型提示
- ✅ 支持 ESLint 配置
安装
npm install -D unplugin-auto-import
# 或
yarn add -D unplugin-auto-import
# 或
pnpm add -D unplugin-auto-import
核心配置选项
1. imports - 自动导入库的 API
作用： 指定要自动导入的库或包的 API。
案例 1.1：字符串形式（最简单）
AutoImport({
imports: [
'vue', // 自动导入 ref, computed, onMounted 等
'vue-router', // 自动导入 useRoute, useRouter 等
'pinia', // 自动导入 defineStore, storeToRefs 等
],
})
使用效果：
<script setup>
// 不需要 import，直接使用
const count = ref(0)
const route = useRoute()
const store = defineStore('user', { ... })
</script>
案例 1.2：对象形式（精确控制）
AutoImport({
imports: [
'vue',
// 只导入指定的 API
{
'vue-router': ['useRoute', 'useRouter'], // 只导入这两个
},
{
'@vueuse/core': [
'useMouse',
'useFetch',
'useLocalStorage',
],
},
{
'axios': [
['default', 'axios'], // 导入默认导出并重命名为 axios
],
},
{
'lodash-es': [
'debounce',
'throttle',
['default', '_'], // 默认导出重命名为 _
],
},
],
})
使用效果：
<script setup>
// 自动导入指定的 API
const { x, y } = useMouse()
const { data } = useFetch('/api/data')
const debouncedFn = debounce(() => {}, 300)
const throttledFn = throttle(() => {}, 300)
</script>
案例 1.3：带别名的导入
AutoImport({
imports: [
{
'vue': [
'ref',
['computed', 'computedRef'], // 导入 computed 并重命名为 computedRef
['onMounted', 'onComponentMount'], // 导入 onMounted 并重命名
],
},
],
})
使用效果：
<script setup>
const count = ref(0)
const double = computedRef(() => count.value * 2) // 使用别名
onComponentMount(() => { // 使用别名
console.log('mounted')
})
</script>
2. dirs - 自动导入自定义目录
作用： 自动导入项目内部目录下的模块（工具函数、composables 等）。
案例 2.1：基本用法
AutoImport({
dirs: [
'./src/utils', // 导入 utils 目录下的所有导出
'./src/composables', // 导入 composables 目录下的所有导出
],
})
项目结构：
src/
utils/
format.js // export const formatDate = ...
validate.js // export const validateEmail = ...
composables/
useAuth.js // export const useAuth = ...
useTable.js // export const useTable = ...
使用效果：
<script setup>
// 自动从 utils 和 composables 导入
const formatted = formatDate(new Date())
const isValid = validateEmail('test@example.com')
const { user, login } = useAuth()
const { data, loading } = useTable()
</script>
案例 2.2：使用 Glob 模式（支持子目录）
AutoImport({
dirs: [
'./src/utils/**', // 包含所有子目录
'./src/composables/**', // 包含所有子目录
'./src/hooks/**/*.ts', // 只匹配 .ts 文件
],
})
案例 2.3：带配置的对象形式
AutoImport({
dirs: [
'./src/utils',
{
// 指定目录
dir: './src/composables',
// 是否生成类型声明（默认 true）
types: true,
// 文件匹配模式
pattern: ['**/*.{ts,js}'],
// 排除某些文件
ignore: ['**/*.test.ts', '**/*.spec.ts'],
},
],
})
案例 2.4：只导入特定文件
AutoImport({
dirs: [
'./src/utils/format.js', // 只导入这个文件
'./src/utils/validate.js', // 只导入这个文件
],
})
⚠️ 注意事项：
-
dirs只能自动导入命名导出（export const、export function） - 不能导入默认导出（
export default），除非使用defaultExportByFilename
3. resolvers - 动态解析器
作用： 动态判断某些标识符应该从哪个模块导入（常用于 UI 库）。
案例 3.1：使用 Element Plus Resolver
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
AutoImport({
resolvers: [
ElementPlusResolver({
// 自动导入样式
importStyle: 'sass', // 或 'css', false
}),
],
})
使用效果：
<script setup>
// 自动导入 ElMessage, ElMessageBox 等
ElMessage.success('成功')
ElMessageBox.confirm('确定？')
</script>
案例 3.2：使用 Vant Resolver
import { VantResolver } from 'unplugin-vue-components/resolvers'
AutoImport({
resolvers: [
VantResolver(),
],
})
使用效果：
<script setup>
// 自动导入 Vant 的函数式 API
showToast('提示')
showDialog({ message: '内容' })
showNotify({ message: '通知' })
</script>
案例 3.3：自定义 Resolver
AutoImport({
resolvers: [
// 自定义 resolver 函数
(name) => {
// 如果函数名以 use 开头，从 @/composables 导入
if (name.startsWith('use')) {
return {
name: name,
from: `@/composables/${name}`,
}
}
// 如果函数名以 $ 开头，从 @/utils 导入
if (name.startsWith('$')) {
return {
name: name.slice(1), // 去掉 $ 前缀
from: `@/utils/${name.slice(1)}`,
}
}
},
],
})
使用效果：
<script setup>
// useAuth 会自动从 @/composables/useAuth 导入
const { user } = useAuth()
// $format 会自动从 @/utils/format 导入（实际导入的是 format）
const date = $format(new Date())
</script>
案例 3.4：多个 Resolver 组合
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'
AutoImport({
resolvers: [
ElementPlusResolver(),
AntDesignVueResolver(),
// 自定义 resolver
(name) => {
if (name === 'myCustomFunction') {
return { name, from: '@/utils/custom' }
}
},
],
})
4. include - 包含文件
作用： 指定哪些文件会被插件处理。
案例 4.1：基本用法
AutoImport({
include: [
/\.[tj]sx?$/, // .ts, .tsx, .js, .jsx
/\.vue$/, // .vue
/\.vue\?vue/, // .vue?vue (SFC)
],
})
案例 4.2：只处理特定文件
AutoImport({
include: [
/\.vue$/, // 只处理 .vue 文件
/src\/views\/.*\.ts$/, // 只处理 views 目录下的 .ts 文件
],
})
案例 4.3：排除测试文件
AutoImport({
include: [
/\.[tj]sx?$/,
/\.vue$/,
],
exclude: [
/\.test\.[tj]sx?$/, // 排除测试文件
/\.spec\.[tj]sx?$/, // 排除测试文件
/node_modules/, // 排除 node_modules
],
})
5. exclude - 排除文件
作用： 排除不需要处理的文件。
案例 5.1：排除特定文件
AutoImport({
exclude: [
/node_modules/, // 排除 node_modules
/\.test\.[tj]sx?$/, // 排除测试文件
/\.spec\.[tj]sx?$/, // 排除测试文件
/dist/, // 排除构建目录
/\.d\.ts$/, // 排除类型声明文件
],
})
案例 5.2：排除特定目录
AutoImport({
exclude: [
/node_modules/,
/src\/components\/legacy/, // 排除旧组件目录
/src\/utils\/deprecated/, // 排除废弃工具目录
],
})
6. dts - 类型声明文件
作用： 生成 TypeScript 类型声明文件，提供类型提示。
案例 6.1：启用类型声明（默认位置）
AutoImport({
dts: true, // 默认生成到根目录的 auto-imports.d.ts
})
案例 6.2：指定类型声明文件路径
AutoImport({
dts: './src/auto-imports.d.ts', // 指定生成位置
})
案例 6.3：禁用类型声明
AutoImport({
dts: false, // 不生成类型声明文件
})
生成的文件示例：
/* eslint-disable */
/* prettier-ignore */
// Generated by unplugin-auto-import
export {}
declare global {
const ElMessage: typeof import('element-plus')['ElMessage']
const computed: typeof import('vue')['computed']
const onMounted: typeof import('vue')['onMounted']
const ref: typeof import('vue')['ref']
const useRoute: typeof import('vue-router')['useRoute']
// ...
}
在 tsconfig.json 中引入：
{
"include": [
"src/auto-imports.d.ts"
]
}
7. eslintrc - ESLint 配置
作用： 生成 ESLint 全局变量配置，避免 no-undef 错误。
案例 7.1：基本配置
AutoImport({
eslintrc: {
enabled: true, // 启用
filepath: './.eslintrc-auto-import.json', // 生成文件路径
globalsPropValue: true, // 设置为全局变量
},
})
生成的 .eslintrc-auto-import.json：
{
"globals": {
"ElMessage": "readonly",
"computed": "readonly",
"onMounted": "readonly",
"ref": "readonly",
"useRoute": "readonly"
}
}
在 .eslintrc.js 中引入：
module.exports = {
extends: [
'./.eslintrc-auto-import.json', // 引入自动生成的配置
],
}
案例 7.2：自定义配置
AutoImport({
eslintrc: {
enabled: true,
filepath: './.eslintrc-auto-import.json',
globalsPropValue: 'readonly', // 或 'writable'
},
})
8. defaultExportByFilename - 按文件名导入
作用： 如果目录下的文件是默认导出，按文件名自动导入。
案例 8.1：启用按文件名导入
AutoImport({
dirs: ['./src/composables'],
defaultExportByFilename: true, // 启用
})
文件结构：
src/composables/
useAuth.js // export default function useAuth() {}
useTable.js // export default function useTable() {}
使用效果：
<script setup>
// 自动从文件名推断导入
const { user } = useAuth() // 从 useAuth.js 导入
const { data } = useTable() // 从 useTable.js 导入
</script>
9. vueTemplate - Vue 模板支持
作用： 在 Vue 模板中也能使用自动导入的 API（实验性功能）。
案例 9.1：启用模板支持
AutoImport({
vueTemplate: true, // 在模板中也能使用自动导入的函数
})
使用效果：
<template>
<!-- 在模板中直接使用 -->
<div>{{ formatDate(date) }}</div>
<button @click="showMessage('Hello')">点击</button>
</template>
10. injectAtEnd - 注入位置
作用： 控制自动导入语句的注入位置。
案例 10.1：在文件末尾注入
AutoImport({
injectAtEnd: true, // 在文件末尾注入 import（默认 false，在文件开头）
})
完整配置示例
Vite 配置示例
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
import path from 'path'
export default defineConfig({
plugins: [
vue(),
AutoImport({
// 1. 自动导入库的 API
imports: [
'vue',
'vue-router',
'pinia',
{
'@vueuse/core': ['useMouse', 'useFetch'],
'lodash-es': ['debounce', 'throttle'],
},
],
// 2. 自动导入自定义目录
dirs: [
'./src/utils/**',
'./src/composables/**',
],
// 3. 动态解析器
resolvers: [
ElementPlusResolver({
importStyle: 'sass',
}),
// 自定义 resolver
(name) => {
if (name.startsWith('use')) {
return { name, from: `@/composables/${name}` }
}
},
],
// 4. 包含的文件
include: [
/\.[tj]sx?$/,
/\.vue$/,
/\.vue\?vue/,
],
// 5. 排除的文件
exclude: [
/node_modules/,
/\.test\.[tj]sx?$/,
/\.spec\.[tj]sx?$/,
],
// 6. 类型声明文件
dts: './src/auto-imports.d.ts',
// 7. ESLint 配置
eslintrc: {
enabled: true,
filepath: './.eslintrc-auto-import.json',
globalsPropValue: true,
},
// 8. 按文件名默认导出
defaultExportByFilename: false,
// 9. Vue 模板支持（实验性）
vueTemplate: false,
// 10. 注入位置
injectAtEnd: false,
}),
],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
})
Webpack 配置示例
const AutoImport = require('unplugin-auto-import/webpack')
module.exports = {
plugins: [
AutoImport({
imports: ['vue', 'vue-router'],
dts: true,
}),
],
}
配置选项总结表
| 选项 | 类型 | 默认值 | 作用 | 常用值 |
|---|---|---|---|---|
imports |
Array<String | Object> |
[] |
自动导入库的 API | ['vue', 'vue-router'] |
dirs |
Array<String | Object> |
[] |
自动导入自定义目录 | ['./src/utils/**'] |
resolvers |
Array<Function> |
[] |
动态解析标识符来源 | [ElementPlusResolver()] |
include |
Array<Regex | String> |
[/\.vue$/, /\.[tj]sx?$/] |
包含的文件模式 | [/\.vue$/, /\.[tj]sx?$/] |
exclude |
Array<Regex | String> |
[/node_modules/] |
排除的文件模式 | [/node_modules/] |
dts |
Boolean | String |
false |
类型声明文件 |
true 或 './src/auto-imports.d.ts'
|
eslintrc |
Object |
{ enabled: false } |
ESLint 配置 | { enabled: true } |
defaultExportByFilename |
Boolean |
false |
按文件名导入 | true |
vueTemplate |
Boolean |
false |
模板支持 | false |
injectAtEnd |
Boolean |
false |
注入位置 | false |
常见问题
Q1: 为什么我的自定义函数没有被自动导入？
A: 检查以下几点：
- 确保函数是命名导出（
export const或export function），不是默认导出 - 检查
dirs配置的路径是否正确 - 确保文件在
include范围内，不在exclude范围内 - 如果使用默认导出，启用
defaultExportByFilename: true
Q2: TypeScript 类型提示不工作？
A:
- 确保
dts配置已启用 - 在
tsconfig.json的include中添加生成的类型声明文件 - 重启 IDE/编辑器
Q3: ESLint 报 no-undef 错误？
A:
- 启用
eslintrc.enabled: true - 在
.eslintrc.js中引入生成的配置文件 - 重启 ESLint 服务
Q4: 如何只导入部分 API？
A: 使用对象形式的 imports 配置：
imports: [
{
'vue': ['ref', 'computed'], // 只导入这两个
},
]
Q5: 如何排除某些文件不被处理？
A: 使用 exclude 配置：
exclude: [
/\.test\.[tj]sx?$/, // 排除测试文件
/node_modules/, // 排除 node_modules
]
Q6: 自定义工具函数如何自动导入？
A:
- 将函数改为命名导出
- 配置
dirs指向函数所在目录 - 使用 Glob 模式支持子目录：
'./src/utils/**'
最佳实践
- 命名导出优先：自定义函数使用命名导出，便于自动导入
-
类型声明文件：始终启用
dts，提供类型提示 -
ESLint 配置：启用
eslintrc，避免no-undef错误 -
精确导入：使用对象形式的
imports，只导入需要的 API -
目录结构：合理组织
utils、composables等目录 -
性能优化：使用
include和exclude限制处理范围
相关链接
- GitHub 仓库
- 官方文档
- unplugin-vue-components（组件自动导入）
更新日志
-
v0.16.0+: 支持
defaultExportByFilename选项 -
v0.15.0+: 改进
dirs的 Glob 模式支持 -
v0.10.0+: 添加
vueTemplate实验性功能
文档版本： 1.0.0
最后更新： 2024年
