模块化已经是现代 Web 开发必不可少的开发方式，频繁引入依赖包是一个常见的操作。但是，手动引入依赖包往往繁琐，尤其是当依赖包数量较多时，会显著降低开发效率。
unplugin-auto-import 插件，可以帮助我们在项目中，自动导入常用的使用的第三方库的 API，就可以方便我们开发，提升开发效率。
使用效果
以 Vue 为例，在没有使用自动导入前，需要手写以下的 import 语句：
import { computed, ref } from 'vue' const count = ref(0) const doubled = computed(() => count.value * 2)
使用 unplugin-auto-import 插件后：
const count = ref(0) const doubled = computed(() => count.value * 2)
使用方法
基本使用
unplugin-auto-import 是基于 unplugin 写的，支持 Vite、Webpack、Rollup、esbuild 多个打包工具。
vite 的使用方式如下：
// vite.config.ts import AutoImport from 'unplugin-auto-import/vite' export default defineConfig({ 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 的预设是怎么写的，完整代码在这里，下面是节选的代码：
export const CommonCompositionAPI: InlinePreset['imports'] = [ // 声明周期，节选 'onActivated', 'onBeforeMount', // reactivity,节选 'computed', 'ref', 'watch', // 组件 API，节选 'defineComponent', 'h', 'inject', 'nextTick', // Typescript 类型，接续那 ...[ 'Component', 'Ref', 'VNode' ].map(name => ({ name, type: true })) ] export default defineUnimportPreset({ 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 {} declare global { const h: typeof import('vue')['h'] const reactive: typeof import('vue')['reactive'] const ref: typeof import('vue')['ref'] const watch: typeof import('vue')['watch'] const watchEffect: typeof import('vue')['watchEffect'] // 省略其他内容 }
unplugin-auto-import 插件会根据预设内容，生成对应的全局类型声明
有了这些全局类型声明，我们就能够像全局变量那样使用 ref 等 Vue API，不需要先 import 对应的内容，TS 编译也不会报错。
Eslint
如果使用了 eslint，需要设置 eslintrc 字段
AutoImport({ eslintrc: { enabled: true, }, })
插件会在项目根目录生成类型文件.eslintrc-auto-import.json ，确保该文件在 eslint 配置中被 extends：
// .eslintrc.js module.exports = { extends: [ './.eslintrc-auto-import.json', ], } .e
slintrc-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
我们直接看看插件代码
export const defaultIncludes = [/\.[jt]sx?$/, /\.vue$/, /\.vue\?vue/, /\.svelte$/] export const defaultExcludes = [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/] export default createUnplugin<Partial<UnimportPluginOptions>>((options = {}) => { const ctx = createUnimport(options) const filter = createFilter( toArray(options.include as string[] || []).length ? options.include : defaultIncludes, options.exclude || defaultExcludes ) const dts = options.dts === true ? 'unimport.d.ts' : options.dts return { name: 'unimport', // 在用户插件执行完之后执行 enforce: 'post', // 过滤文件，默认只处理 、js、jsx、ts、tsx、vue、svelte 文件 // 默认排除 node_modules 下的文件 transformInclude (id) { return filter(id) }, // 转换文件逻辑 async transform (code, id) { const s = new MagicString(code) // 注入 import 语句 await ctx.injectImports(s, id) if (!s.hasChanged()) { return } return { code: s.toString(), map: s.generateMap() } }, // 构建开始时，生成 ts 类型声明文件 async buildStart () { await ctx.init() // 生成 Typescript 全局类型声明 if (options.dts) { return fs.writeFile(dts, await ctx.generateTypeDeclarations(), 'utf-8') } } } })
插件用基于 unplugin 写的，用 unplugin 写的插件，能用在 Vite、Webpack、Rollup、esbuild 多个打包工具，即**unplugin 抹平了打包工具间的一些差异**。
unimport 插件主要的处理逻辑如下：
- 过滤出需要处理的文件，对文件进行转换，注入 import 语句
- 生成 ts 类型声明文件
unimport为什么需要在其他插件后执行？
因为有些代码需要先经过处理，才会变成 js，例如 Vue 文件。
测试用例
我们直接使用 unimport 提供的示例，其中一个文件为：
import { Ref } from 'vue' export const multiplier = ref(2) export function useDoubled (v: Ref<number>) { return computed(() => v.value * multiplier.value) } export function bump () { multiplier.value += 1 } const localA = 'localA' const localB = 'localB' export { localA, localB as localBAlias }
我们通过 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' export const multiplier = ref(2) export function useDoubled (v: Ref<number>) { return computed(() => v.value * multiplier.value) } export function bump () { multiplier.value += 1 } const localA = 'localA' const localB = 'localB' export { localA, localB as localBAlias }
以上述文件为例，从中找出没有先定义再使用的标志符，排除 js 关键字（function 等）
可以查找到有以下的标志符，未被定义却使用了：
- ref
- computed
并且这两个标志符都在 importMap 中能找到，这标明这两个标志符，需要注入 import
因此会注入以下代码：
import { ref, computed } from 'vue';
总结
并非所以依赖都适合自动导入，项目内的代码可能就不一定适合自动引入
因为自动引入后，就能像全局变量那样直接使用，但从开发的角度就会丢失依赖链路，虽然另外生成了 Typescript 声明文件，IDE 能够正常识别， 但对于新加入项目的同学来说，他们不一定知道是自动引入，因此可能会降低了一些可读性。
因此我们要有权衡。
那么，什么样的内容适合自动引入？被广泛认知和使用、不用关注实现、不变的内容
这些内容不关注实现，不会影响可读性，不会影响开发，不会对开发者心智造成影响。
这类内容，就适合自动引入。例如我们例子中的 Vue composition API，就已经成为一种 Vue 开发者共识了。
如果这篇文章对您有所帮助，可以点赞加收藏👍，您的鼓励是我创作路上的最大的动力。也可以关注我的公众号订阅后续的文章：Candy 的修仙秘籍（点击可跳转）
