随笔，告别手动引入依赖：unplugin-auto-import 插件助你提升编码体验（内附实现原理）

模块化已经是现代 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',
  ],
}

.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

我们直接看看插件代码

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 插件主要的处理逻辑如下：

  1. 过滤出需要处理的文件，对文件进行转换，注入 import 语句
  2. 生成 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 插件，可以看到该文件被转换的过程：

  1. 被 esbuild 转换
  1. 被 unimport 插件转换

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

  1. 被 import-analysis 插件处理

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

如何注入 import 语句

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

  1. 初始化预设
  2. 扫描文件
  3. 注入 import

初始化预设

  1. 将字符串的内置预设，标准化为对象语法
  2. 将所有配置对象合并成一个 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 对象，就可以快速判断一个标志符，是否需要转换了

扫描和注入

  1. 查找所有可能需要注入的标志符
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 的修仙秘籍（点击可跳转）

另外，腾讯的实习生校招也开始了，感兴趣的也可以通过公众号找我内推（内推的话先不要到官网填简历）。

正文完
2021-06-08