vue3+vite 实现依赖自动导入（unplugin-auto-import）

作用

实现依赖的自动导入，不用再频繁导入依赖包，从而提交我们的开发效率。

例如可以避免在每个vue组件中都重复性的去声明ref、reactive等函数。配置之后，组件中需要用到ref、reactive等函数时就可以忽略不写下面语句。

import {ref,reactive} from 'vue'

使用教程（vue3+vite+js）

安装依赖包

npm install unplugin-auto-import@0.17.2 --save-dev

配置

打开vite.config.js文件，在plugins选项中配置AutoImport。

import autoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins:[
    vue(),
    AutoImport(
      {
        imports:[
          'vue', //自动导入vue的相关函数，例如ref、reactive、toRef等
          'vue-router',
          'pinia']
      }
    )
  ]
})

运行项目

重新运行项目后，本地src目录下会生成auto-import.d.ts文件。至此组件中就可以在不需要引入的情况下使用ref、reactive等api函数。

扩展

按照上述步骤配置完之后，若页面中使用相关api函数出现红色警告，则可以按照以下方式解决（本人没遇到过，可能是需要开启Eslint功能才会出现，解决方案摘抄自网络，不保真）

打开tsconfig.json 或者 jsconfig.json 配置文件，在include变量里加上下列配置。（不知道哪个是对的，每个都试一下）

"include":["auto-imports.d.ts"]
"include":["./auto-imports.d.ts"] 
"include": ["typings/*.d.ts"]
"include": ["typings/**/*.d.ts"] 

使用教程（vue3+vite+ts）

安装依赖包

npm install unplugin-auto-import@0.17.5 --save-dev

按需引入配置

打开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","@vueuse/core","pinia","vue-router","vue-i18n"]
     })
  ]
})

使用 imports 初始化导入依赖库，然后在项目中使用依赖库的函数就不需要再引入依赖库了。

<template>
  <div>
    <el-button @click="increment">计数: {{ count }}</el-button>
  </div>
</template>

<script setup>
// 无需 import { ref, computed } from 'vue'
const count = ref(0)
const increment = () => count.value++

// 无需 import { useRouter } from 'vue-router'
const router = useRouter()

// 无需 import { useStore } from 'pinia'
const store = useStore()
</script>

自动导入ElementPlus组件

1. 关联插件：unplugin-vue-components，结合autoimport，主要用于导入 ElementPlus 提供的 API 函数（如 ElMessage、ElNotification 等）。

npm install unplugin-vue-components --save-dev

2. 配置如下：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

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

export default defineConfig({
  plugins:[
    vue(),
    AutoImport({
       resolvers:[
        ElementPlusResolver()
       ]
     })
  ]
})

3. 页面中使用ElementPlus的Api函数不需要再引入了。

// 自动导入 ElMessage 等 API
import { ElMessage } from 'element-plus'

// 使用时无需手动导入
ElMessage.success('操作成功')

自动导入图标组件

1. 关联插件

unplugin-icons，需在 plugins 中添加 Icons() 插件。

npm install unplugin-icons --save-dev

图标库可以选择 @iconify-json/ep 或者 @element-plus/icons-vue。

npm install @iconify-json/ep --save-dev

npm install @element-plus/icons-vue --save

这里选择使用 ElementPlus 图标库并通过 Iconify 的方式来实现图标解析和自动导入等功能。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import AutoImport from "unplugin-auto-import/vite";
import Icons from "unplugin-icons/vite";
import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/vite"

export default defineConfig({
  plugins:[
    vue(),
    AutoImport({
       resolvers:[
        IconsResolver({})
       ]
     }),
    Components({
      resolvers: [
          IconsResolver({
            //prefix: 'Icon', 
            enabledCollections: ["ep"],
          }),
        ],
    }),
    Icons({
      // 自动安装图标库
      autoInstall: true,
    })
  ]
})

autoInstall: true 是 unplugin-icons 插件的一项功能，用于自动安装项目中使用到但未预先安装的图标库。

页面使用：i-ep-xxx 格式。

查询：<i-ep-search /><br/>
降序：<i-ep-caret-top /><br/>
升序：<i-ep-caret-bottom /><br/>
编辑：<i-ep-edit /><br/>
删除：<i-ep-delete /><br/>
添加：<i-ep-plus /><br/>
关闭：<i-ep-close /><br/>
刷新：<i-ep-refresh /><br/>
字典：<i-ep-Collection /><br/>
分配：<i-ep-position />

prefix：可选配置，如果不配置则默认使用的 i-ep-xxx 格式。如果配置了前缀prefix，例如 prefix: 'Icon'，则图标组件的名称前缀会由 i 变成 icon，有两种结构：

1. iconEp+图标名称：这种格式下icon的首字母 i 和 图标名称的首字母可以忽略大小写，例如：

<iconEpsearch/>
<iconEpSearch/>  
<IconEpsearch/>  
<IconEpSearch/>  

2. icon-ep-图标名称：这种格式下icon、ep、图标名称的首字母可以忽略大小写，例如：

<icon-ep-search/>
<icon-ep-Search/>
<icon-Ep-search/>
<icon-Ep-Search/>
<Icon-ep-search/>
<Icon-ep-Search/>
<Icon-Ep-search/>
<Icon-Ep-Search/>

效果：

自动导入自定义组件目录

dirs：可选配置，如果不配置则 unplugin-vue-components 默认只会扫描 src/components 目录下的组件，其他目录组件需手动导入，不会被自动导入，配置了 src/**/components" 之后可以在 src 目录及其子目录下的所有 components 目录中查找组件。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import Components from "unplugin-vue-components/vite"

export default defineConfig({
  plugins:[
    vue(),
    Components({
      dirs:["src/components","src/**/components"]
    }),
  ]
})

是否自动生成类型声明文件

1. dts：是否禁用自动生成类型声明文件（.d.ts）；

• autoImport旧版本（<= 0.15.x）：dts 默认值为 false，需手动启用。
• autoImport新版本（>= 0.16.0）：dts 默认值为 'auto-imports.d.ts'，会自动生成类型声明文件 auto-imports.d.ts 到项目根目录。
• Components插件中，dts 默认值为 true，在项目根目录下会自动生成components.d.ts 文件。

AutoImport({
  dts: false
}),
Components({
  dts: false
})

2. 适用场景：不需要 TypeScript 类型提示，或项目已有手动维护的类型文件。
3. 效果：

• 不会生成 components.d.ts 或 auto-imports.d.ts 文件。
• 在模板中使用自动导入的组件 / 函数时，TypeScript 无法提供自动补全和类型检查（如 VSCode 不会提示组件属性）。

4. Components 和 AutoImport 都可以设置dts，但是他们控制不同类型的自动导入。

• Components插件的dts：控制组件的类型声明文件（如 ElementPlus 组件、自定义组件）。

Components({
  dts: 'src/typings/components.d.ts', // 生成组件类型声明
})

• AutoImport插件的dts：控制函数的类型声明文件（如 ref、computed、ElementPlus函数）。

AutoImport({
  dts: 'src/typings/auto-imports.d.ts', // 生成函数类型声明
})

在vue模板中支持自动导入

vueTemplate: true ：允许在 Vue 模板 template 中直接使用自动导入的 API，无需在 script 中显式引入。

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

export default defineConfig({
  plugins:[
    vue(),
    AutoImport({
       vueTemplate: true
     })
  ]
})

自动生成eslint规则

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

export default defineConfig({
  plugins:[
    vue(),
    AutoImport({
        eslintrc: {
          enabled: false, //第一次运行
          filepath: "./.eslintrc-auto-import.json",
          globalsPropValue: true
       }
     })
  ]
})

1. 作用：自动生成 ESLint 规则，从而避免在使用自动导入的 API 时出现 “未定义变量” 的报错。
2. enabled：

• 当设置为 true 时，插件会自动生成 ESLint 配置文件，把自动导入的 API 声明为全局变量。当设置为 false时，禁用自动生成规则文件。
• 建议在首次运行项目或者需要更新规则时启用该选项（设置为 true），生成配置文件之后就可以将其关闭（设为 false），这样能避免重复生成文件。

filepath：

• 此选项用于指定生成的 ESLint 配置文件的路径。
• 生成的文件会包含自动导入 API 的全局变量声明，在 ESLint 配置中应当引入这个文件。

globalsPropValue：

• 该选项决定如何为全局变量设置属性值，不显示设置该属性，会按 true 的方式处理。
• 设为 true 时，会使用 "readonly"（只读）；设为 false 时，值为 "writable"（可写）；也可以直接指定具体的值，像 "readonly"。(新版本因为设置为true/false生成的不是"readonly" /"writable"，所以如果要强制生成可以指定具体的值)

注意：从0.16+版本开始，**globalsPropValue**** 被简化为bool值，，直接映射为 ESLint 的 **true**（可写）或 **false**（禁用），不再支持 **"readonly"** 或 **"writable"**，而是通过 **true/false** 控制变量是否被 ESLint 识别，true 对应的是 "readonly"，false 对应的是 "writable"。**

 globalsPropValue: 'readonly'

3. 运行项目后会生成 .eslintrc-auto-import.json 文件，其内容示例如下：

//旧版本
{
  "globals": {
    "ref": "readonly",
    "computed": "readonly",
    // 其他自动导入的API
  }
}

//新版本
{
  "globals": {
    "ref": true,
    "computed": true,
    // 其他自动导入的API
  }
}

4. 生成文件之后在 .eslintrc.js 或者其他 ESLint 配置文件中引入生成的规则：

module.exports = {
  extends: [
    // 其他扩展...
    "./.eslintrc-auto-import.json",
  ],
};

完整配置

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

import AutoImport from "unplugin-auto-import/vite";
import Icons from "unplugin-icons/vite";
import { ElementPlusResolver } from "unplugin-vue-components/resolvers";
import IconsResolver from "unplugin-icons/resolver";
import Components from "unplugin-vue-components/vite"

export default defineConfig({
  plugins:[
    vue(),
    AutoImport({
       imports:["vue","@vueuse/core","pinia","vue-router","vue-i18n"],
       resolvers:[
        ElementPlusResolver(),
        IconsResolver({})
       ],
       eslintrc: {
          enabled: false,
          filepath: "./.eslintrc-auto-import.json",
          globalsPropValue: true
       },
       vueTemplate: true,
       dts: "src/typings/auto-imports.d.ts"
    }),
    Components({
      resolvers: [
          ElementPlusResolver()
          IconsResolver({
          enabledCollections: ["ep"],
          }),
        ],
      dirs:["src/components","src/**/components"]
    }),
    Icons({
        autoInstall: true,
    })
  ]
})

运行项目生成文件

运行项目后，项目根目录下会生成 auto-imports.d.ts 、 components.d.ts 、.eslintrc-auto-import.json文件。