模块化已经是现代 Web 开发必不可少的开发方式，频繁引入依赖包是一个常见的操作。但是，手动引入依赖包往往繁琐，尤其是当依赖包数量较多时，会显著降低开发效率。

unplugin-auto-import 插件，可以帮助我们在项目中，自动导入常用的使用的第三方库的 API，就可以方便我们开发，提升开发效率。

使用效果

以 Vue 为例，在没有使用自动导入前，需要手写以下的 import 语句：

import{computed,ref}from'vue'constcount=ref(0)constdoubled=computed(()=>count.value*2)

使用 unplugin-auto-import 插件后：

constcount=ref(0)constdoubled=computed(()=>count.value*2)

使用方法

基本使用

unplugin-auto-import 是基于 unplugin 写的，支持 Vite、Webpack、Rollup、esbuild 多个打包工具。

vite 的使用方式如下：

// vite.config.tsimportAutoImportfrom'unplugin-auto-import/vite'exportdefaultdefineConfig({plugins:[AutoImport({imports:[// 预设],}),],})

使用预设

unplugin-auto-import 插件一般配合预设进行使用，预设负责告诉插件应该自动引入哪些内容

目前支持：

Vue

vue-router

@vueuse/core

react

react-router

……，更多请查看这里

预设的配置方式

AutoImport({imports[// 预设'vue','vue-router',// 自定义预设{'@vueuse/core':[// 命名导入'useMouse',// import { useMouse } from '@vueuse/core',// 设置别名['useFetch','useMyFetch'],// import { useFetch as useMyFetch } from '@vueuse/core',],'axios':[// 默认导入['default','axios'],// import { default as axios } from 'axios',],'[package-name]':['[import-names]',// alias['[from]','[alias]'],],},// example type import{from:'vue-router',imports:['RouteLocationRaw'],type:true,},],})

有多种方式设置预设：

字符串语法，最终会被转换成内置的预设（对象语法写的）

对象语法

key 为包名

value 为数组，对应的是各个自动引入的变量的名称。同时可以设置引入方式（命名导入/默认导入），

对于 Typescript 类型的自动引入，则需要用以下方式：

{from:'vue-router',imports:['RouteLocationRaw'],type:true},

我们来看看 Vue 的预设是怎么写的，完整代码在这里，下面是节选的代码：

exportconstCommonCompositionAPI:InlinePreset['imports']=[// 声明周期，节选'onActivated','onBeforeMount',// reactivity,节选'computed','ref','watch',// 组件 API，节选'defineComponent','h','inject','nextTick',// Typescript 类型，接续那...['Component','Ref','VNode'].map(name=>({name,type:true}))]exportdefaultdefineUnimportPreset({from:'vue',imports:[...CommonCompositionAPI,]})

Vue 预设里，本质就是使用对象语法，定义了 Vue 需要被自动导入的内容。

编码问题

要想在项目中优雅地使用自动导入，还要解决以下两个编码的问题：

TS 类型丢失，会导致 TS 编译报错

Eslint 报错：变量未定义

TS 类型

如果使用 Typescript，需要设置 dts 为 true

AutoImport({dts:true// or a custom path})

插件会在项目根目录生成类型文件 auto-imports.d.ts ，确保该文件在 tsconfig 中被 include

auto-imports.d.ts 有什么作用？

我们来看看它的内容（有节选）：

export{}declareglobal{consth:typeofimport('vue')['h']constreactive:typeofimport('vue')['reactive']constref:typeofimport('vue')['ref']constwatch:typeofimport('vue')['watch']constwatchEffect:typeofimport('vue')['watchEffect']// 省略其他内容}

unplugin-auto-import 插件会根据预设内容，生成对应的全局类型声明

有了这些全局类型声明，我们就能够像全局变量那样使用 ref 等 Vue API，不需要先 import 对应的内容，TS 编译也不会报错。

Eslint

如果使用了 eslint，需要设置 eslintrc 字段

AutoImport({eslintrc:{enabled:true,},})

插件会在项目根目录生成类型文件 .eslintrc-auto-import.json ，确保该文件在 eslint 配置中被 extends：

// .eslintrc.jsmodule.exports={extends:['./.eslintrc-auto-import.json',],}

.eslintrc-auto-import.json 有什么作用？

我们来看看它的内容（有节选）：

{"globals":{"h":true,"reactive":true,"ref":true,"watch":true,"watchEffect":true,}}

unplugin-auto-import 插件会根据预设内容，生成对应的 eslint 配置文件，该文件定义了 h、ref 这些为全局变量，不需要引入就能直接使用。这样 ESlint 就不会报变量没有定义的错误了。

实现原理

从 v0.8.0 来开始，unplugin-auto-import 基于 unimport 开发，所有的转换能力，都是 unimport 提供的，unplugin-auto-import 可以理解成为一个提供了更友好的 API 和功能的包装层。基本上所有新功能都会在 unimport 中开发。

那核心的实现，我们直接去看 unimport 就好了。

eslint 配置的生成是由 unplugin-auto-import 提供

unimport

我们直接看看插件代码

exportconstdefaultIncludes=[/\.[jt]sx?$/,/\.vue$/,/\.vue\?vue/,/\.svelte$/]exportconstdefaultExcludes=[/[\\/]node_modules[\\/]/,/[\\/]\.git[\\/]/]exportdefaultcreateUnplugin<Partial<UnimportPluginOptions>>((options={})=>{constctx=createUnimport(options)constfilter=createFilter(toArray(options.includeasstring[]||[]).length?options.include:defaultIncludes,options.exclude||defaultExcludes)constdts=options.dts===true?'unimport.d.ts':options.dtsreturn{name:'unimport',// 在用户插件执行完之后执行enforce:'post',// 过滤文件，默认只处理 、js、jsx、ts、tsx、vue、svelte 文件// 默认排除 node_modules 下的文件transformInclude(id){returnfilter(id)},// 转换文件逻辑asynctransform(code,id){consts=newMagicString(code)// 注入 import 语句awaitctx.injectImports(s,id)if(!s.hasChanged()){return}return{code:s.toString(),map:s.generateMap()}},// 构建开始时，生成 ts 类型声明文件asyncbuildStart(){awaitctx.init()// 生成 Typescript 全局类型声明if(options.dts){returnfs.writeFile(dts,awaitctx.generateTypeDeclarations(),'utf-8')}}}})

插件用基于 unplugin 写的，用 unplugin 写的插件，能用在 Vite、Webpack、Rollup、esbuild 多个打包工具，即unplugin 抹平了打包工具间的一些差异。

unimport 插件主要的处理逻辑如下：

过滤出需要处理的文件，对文件进行转换，注入 import 语句

生成 ts 类型声明文件

unimport 为什么需要在其他插件后执行？

因为有些代码需要先经过处理，才会变成 js，例如 Vue 文件。

测试用例

我们直接使用 unimport 提供的示例，其中一个文件为：

import{Ref}from'vue'exportconstmultiplier=ref(2)exportfunctionuseDoubled(v:Ref<number>){returncomputed(()=>v.value*multiplier.value)}exportfunctionbump(){multiplier.value+=1}constlocalA='localA'constlocalB='localB'export{localA,localBaslocalBAlias}

我们通过 vite-plugin-inspect 插件，可以看到该文件被转换的过程：

被 esbuild 转换

被 unimport 插件转换

可以看出 unbuild 插件自动加入了 import 语句

被 import-analysis 插件处理

将 Vue 改为一个可以访问的路径，让 vue 的相关文件在 dev 环境下能够被正常访问到。

如何注入 import 语句

注入 import 语句，是 unimport 的核心逻辑，主要有以下几个步骤：

初始化预设

扫描文件

注入 import

初始化预设

将字符串的内置预设，标准化为对象语法

将所有配置对象合并成一个 importMap 对象

importMap 数据结构如下：

{reactive:{from:'vue,        name: 'reactive'        as: 'reactive'    },  // 转换成 import { reactive } from 'vue'    ref: {        from: 'vue,name:'ref        as: 'ref},// 转换成 import { ref } from 'vue'// ……}

有了 importMap 对象，就可以快速判断一个标志符，是否需要转换了

扫描和注入

查找所有可能需要注入的标志符

import{Ref}from'vue'exportconstmultiplier=ref(2)exportfunctionuseDoubled(v:Ref<number>){returncomputed(()=>v.value*multiplier.value)}exportfunctionbump(){multiplier.value+=1}constlocalA='localA'constlocalB='localB'export{localA,localBaslocalBAlias}

以上述文件为例，从中找出没有先定义再使用的标志符，排除 js 关键字（function 等）

可以查找到有以下的标志符，未被定义却使用了：

ref

computed

并且这两个标志符都在 importMap 中能找到，这标明这两个标志符，需要注入 import

因此会注入以下代码：

import{ref,computed}from'vue';

总结

并非所以依赖都适合自动导入，项目内的代码可能就不一定适合自动引入

因为自动引入后，就能像全局变量那样直接使用，但从开发的角度就会丢失依赖链路，虽然另外生成了 Typescript 声明文件，IDE 能够正常识别， 但对于新加入项目的同学来说，他们不一定知道是自动引入，因此可能会降低了一些可读性。

因此我们要有权衡。

那么，什么样的内容适合自动引入？被广泛认知和使用、不用关注实现、不变的内容

这些内容不关注实现，不会影响可读性，不会影响开发，不会对开发者心智造成影响。

这类内容，就适合自动引入。例如我们例子中的 Vue composition API，就已经成为一种 Vue 开发者共识了。