unplugin-auto-import：按需自动导入 API 的构建工具插件

本文介绍 unplugin-auto-import，一个为 Vite、Webpack、Rollup 等构建工具提供按需自动导入 API 功能的插件。

unplugin-auto-import 简介

unplugin-auto-import 是由 Anthony Fu (antfu) 开发的开源插件，基于 unplugin 构建，为 Vite、Webpack、Rspack、Rollup 和 esbuild 提供按需自动导入 API 的功能。该项目在 GitHub 上拥有 3.8k stars 和 218 forks，采用 MIT 许可证。

核心定位：Auto import APIs on-demand for Vite, Webpack and Rollup

核心功能

该插件的核心价值在于消除重复的 import 语句，让开发者可以直接使用 API 而无需手动导入：

使用前后对比

Vue 示例 - 使用前：

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

Vue 示例 - 使用后：

const count = ref(0)
const doubled = computed(() => count.value * 2)

React 示例 - 使用前：

tsx

import { useState } from 'react'
export function Counter() {
  const [count, setCount] = useState(0)
  return <div>{ count }</div>
}

React 示例 - 使用后：

tsx

export function Counter() {
  const [count, setCount] = useState(0)
  return <div>{ count }</div>
}

安装方法

bash

npm i -D unplugin-auto-import

支持的工具链

工具	导入路径
Vite	`unplugin-auto-import/vite`
Rollup	`unplugin-auto-import/rollup`
Rolldown	`unplugin-auto-import/rolldown`
Webpack	`unplugin-auto-import/webpack`
Rspack	`unplugin-auto-import/rspack`
esbuild	`unplugin-auto-import/esbuild`
Astro	`unplugin-auto-import/astro`
Quasar	`unplugin-auto-import/vite`

注意：Nuxt 已内置此功能，无需额外安装。

配置示例

Vite 配置

// vite.config.ts
import { defineConfig } from 'vite'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    AutoImport({
      // 目标文件
      include: [
        /\.[tj]sx?$/,
        /\.vue$/,
        /\.vue\?vue/,
        /\.md$/,
      ],
      // 自动导入的预设
      imports: [
        // Vue
        'vue',
        // Vue Router
        'vue-router',
        // VueUse
        '@vueuse/core',
      ],
      // 生成类型声明文件
      dts: true,
      // 生成 ESLint 配置
      eslintrc: {
        enabled: true,
      },
    }),
  ],
})

Webpack 配置

// webpack.config.js
const AutoImport = require('unplugin-auto-import/webpack')

module.exports = {
  plugins: [
    AutoImport({
      imports: ['react', 'react-router'],
      dts: true,
    }),
  ],
}

核心配置选项

选项	说明
`include`	目标文件匹配模式，支持 `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.md` 等
`imports`	全局导入注册，支持 presets 和自定义导入
`dirs`	扫描指定目录自动导入
`dts`	生成 TypeScript 声明文件，默认 `./auto-imports.d.ts`
`eslintrc`	生成 ESLint 配置文件
`biomelintrc`	生成 Biome 配置文件
`vueTemplate`	启用 Vue 模板内的自动导入
`viteOptimizeDeps`	Vite 依赖优化

预设支持

内置预设位于 src/presets，支持：

vue - Vue 3 Composition API
vue-router - Vue Router
@vueuse/core - VueUse 工具库
react - React Hooks
react-router - React Router
pinia - Pinia 状态管理
quasar - Quasar 框架
自定义包预设 (packagePresets)

自定义导入

AutoImport({
  imports: [
    // 预设
    'vue',
    // 自定义导入
    {
      // 从包导入
      'axios': [
        ['default', 'axios'],
      ],
      // 自定义模块
      '@/utils': [
        'formatDate',
        'parseJSON',
      ],
    },
  ],
})

目录扫描自动导入

AutoImport({
  dirs: [
    // 扫描 composables 目录
    './src/composables/**',
    // 扫描 utils 目录
    './src/utils/**',
  ],
})

TypeScript 支持

启用 dts: true 自动生成类型声明文件：

// auto-imports.d.ts（自动生成）
export {}
declare global {
  const ref: typeof import('vue')['ref']
  const computed: typeof import('vue')['computed']
  const watch: typeof import('vue')['watch']
  // ...
}

确保 auto-imports.d.ts 未被 tsconfig.json 排除。

ESLint 集成

AutoImport({
  eslintrc: {
    enabled: true,
    filepath: './.eslintrc-auto-import.json',
    globalsPropValue: true,
  },
})

然后在 .eslintrc 中：

json

{
  "extends": ["./.eslintrc-auto-import.json"]
}

实际应用示例

Vue 3 项目

vue

<script setup>
// 无需导入，直接使用
const count = ref(0)
const doubled = computed(() => count.value * 2)
const router = useRouter()

function increment() {
  count.value++
}

// VueUse
const { x, y } = useMouse()
</script>

React 项目

tsx

function App() {
  // 无需导入 useState
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  )
}

优势与注意事项

优势

减少样板代码：无需重复编写 import 语句
提升开发效率：直接使用熟悉的 API
TypeScript 友好：自动生成类型声明
工具链广泛：支持主流构建工具
灵活配置：支持预设、自定义导入、目录扫描

注意事项

团队协作：需要确保团队成员了解自动导入机制
代码可读性：新成员可能不清楚 API 来源
IDE 支持：需要正确配置类型声明文件

项目信息

GitHub 仓库：https://github.com/unplugin/unplugin-auto-import
NPM 包：https://www.npmjs.com/package/unplugin-auto-import
作者：Anthony Fu (@antfu)
星标数：3.8k stars
许可证：MIT

总结

unplugin-auto-import 是一个实用的开发工具，通过自动导入机制显著减少样板代码，提升开发效率。其核心优势包括：

广泛兼容：支持 Vite、Webpack、Rollup 等主流工具
TypeScript 原生支持：自动生成类型声明
预设丰富：内置 Vue、React、VueUse 等常用预设
灵活扩展：支持自定义导入和目录扫描
生态成熟：基于 unplugin，与前端生态深度集成

对于使用 Vue 3、React 等现代前端框架的开发者来说，unplugin-auto-import 是提升开发体验的利器。