Vue3 使用 unplugin-auto-import 配置自动导入

一、前言

在Vue3开发中，我们经常需要频繁导入使用vue、vue-router、pinia等库的API，如ref、reactive、onMounted、useRoute等。每次都要手动编写import语句既繁琐又影响开发效率。unplugin-auto-import插件可以帮助我们自动导入这些API，无需手动编写import语句，大大提升开发效率。

二、unplugin-auto-import 简介

unplugin-auto-import 是一个 Vite/Webpack/Rollup 插件，用于自动导入 API，支持 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. 配置 vite.config.ts

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import AutoImport from "unplugin-auto-import/vite";

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      imports: ["vue", "vue-router", "pinia"],
    }),
  ],
});

2. 使用效果

配置完成后，在Vue组件中可以直接使用自动导入的API，无需手动导入：

<script setup lang="ts">
// 不需要 import，直接使用
const count = ref(0)
const route = useRoute()
const store = defineStore('user', { ... })
</script>

五、TypeScript 配置

引入TypeScript时，需要进行额外的类型声明配置，否则会出现TS报错。

1. 生成类型声明文件

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import AutoImport from "unplugin-auto-import/vite";

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      imports: ["vue", "vue-router", "pinia"],
      dts: "src/types/auto-import.d.ts",
    }),
  ],
});

2. tsconfig.json 配置

{
  "include": [
    "src/**/*.js",
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.jsx",
    "src/**/*.vue",
    "./src/types/auto-import.d.ts"
  ]
}

六、ESLint 配置

配置完成后，虽然可以正常使用API，但ESLint可能还会报错提示找不到变量。

1. 生成 ESLint 配置文件

AutoImport({
  imports: ["vue", "vue-router", "pinia"],
  eslintrc: {
    enabled: true,
  },
});

2. .eslintrc.js 中引入

module.exports = {
  root: true,
  extends: ["./.eslintrc-auto-import.json"],
};

七、imports 配置详解

1. 字符串形式（最简单）

1
2
3

AutoImport({
  imports: ["vue", "vue-router", "pinia"],
});

2. 对象形式（精确控制）

AutoImport({
  imports: [
    "vue",
    {
      "vue-router": ["useRoute", "useRouter"],
      "@vueuse/core": ["useMouse", "useFetch", "useLocalStorage"],
    },
  ],
});

3. 带别名的导入

AutoImport({
  imports: [
    {
      vue: [
        "ref",
        ["computed", "computedRef"],
        ["onMounted", "onComponentMount"],
      ],
    },
  ],
});

八、dirs 配置（自动导入自定义目录）

自动导入项目内部目录下的模块（工具函数、composables等）。

1. 基本用法

1
2
3

AutoImport({
  dirs: ["./src/utils", "./src/composables"],
});

2. 使用 Glob 模式（支持子目录）

1
2
3

AutoImport({
  dirs: ["./src/utils/**", "./src/composables/**", "./src/hooks/**/*.ts"],
});

九、resolvers 配置（动态解析器）

用于UI库的自动导入，如Element Plus、Vant等。

配合 Element Plus 使用

import AutoImport from "unplugin-auto-import/vite";
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";

AutoImport({
  resolvers: [ElementPlusResolver()],
});