项目集成自动导入 API

在 Vue3 开发过程中，我们经常需要手动导入 ref、computed、watch 等 Vue API，同时 vue-router 的 useRouter()、useRoute() 以及 Pinia 的 defineStore() 也需要手动 import，例如：

import { ref, computed } from 'vue';
import { useRouter, useRoute } from 'vue-router';
import { defineStore } from 'pinia';

在多个文件中反复导入这些 API 非常繁琐，同时如果某些 import 遗漏，会导致 TS 报错。

为了解决这个问题，我们可以使用 unplugin-auto-import 自动导入 Vue、Vue Router、Pinia 的 API，这样我们在代码中就可以直接使用这些 API，而不需要手动导入，提高开发效率！

---

1. 为什么使用 unplugin-auto-import？

• ✅ 无需手动 import Vue、Vue Router、Pinia 的 API，减少代码冗余。
• ✅ TypeScript 友好，自动生成类型声明文件，避免 TS 报错。
• ✅ 支持 ESLint 规则，保证代码风格一致，不影响静态检查。
• ✅ 可扩展性强，可以配置自动导入 VueUse、Axios 等工具库的 API。

---

2. 安装 unplugin-auto-import

使用 pnpm 安装：

pnpm install -D unplugin-auto-import

或者使用 npm / yarn：

npm install -D unplugin-auto-import
# 或
yarn add -D unplugin-auto-import

---

3. 在 vite.config.ts 配置插件

安装完成后，需要在 vite.config.ts 启用 unplugin-auto-import，让其自动导入 Vue、Vue Router、Pinia 的 API。

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', 'vue-router', 'pinia'], // 自动导入 Vue & Vue Router & Pinia API
      dts: 'src/auto-imports.d.ts', // 生成全局类型声明，支持 TypeScript
      eslintrc: {
        enabled: true, // 生成 `.eslintrc-auto-import.json`，自动配置 ESLint
      },
    }),
  ],
});

📌 配置解析

• imports: ['vue', 'vue-router', 'pinia'] 👉 自动导入 ref、computed、useRouter()、defineStore() 等 API。
• dts: 'src/auto-imports.d.ts' 👉 自动生成 TypeScript 类型声明，避免 TS 报 Cannot find name 'ref'。
• eslintrc.enabled: true 👉 自动配置 ESLint，避免 ESLint 报 no-undef 错误。

---

4. 配置成功后代码使用

📌 1. 不用再手动 import

有了 unplugin-auto-import，我们可以直接使用 Vue API，而不需要手动 import：

<script setup lang="ts">
const count = ref(0);
const double = computed(() => count.value * 2);
</script>

而不需要：

<script setup lang="ts">
import { ref, computed } from 'vue';

const count = ref(0);
const double = computed(() => count.value * 2);
</script>

✅ ref 和 computed 会被自动导入，不需要 import！

---

📌 2. vue-router 直接使用 useRouter()

如果项目中使用 vue-router，我们可以直接使用 useRouter()，而不需要手动导入：

<script setup lang="ts">
const router = useRouter();

const goHome = () => {
  router.push('/');
};
</script>

📌 无需 import { useRouter } from 'vue-router'，插件会自动导入！

---

📌 3. Pinia 直接使用 defineStore()

如果项目中使用了 Pinia，我们可以直接使用 defineStore() 创建状态管理：

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  actions: {
    increment() {
      this.count++;
    },
  },
});

📌 无需 import { defineStore } from 'pinia'，插件会自动导入！

---

5. 自动生成 TypeScript 类型

如果你的项目是 Vue3 + TypeScript，unplugin-auto-import 会自动生成全局类型声明，避免 TS 报错。

📌 自动生成 src/auto-imports.d.ts

// 这个文件是自动生成的，避免手动 import
declare global {
  const ref: typeof import('vue')['ref'];
  const computed: typeof import('vue')['computed'];
  const watch: typeof import('vue')['watch'];
  const useRouter: typeof import('vue-router')['useRouter'];
  const defineStore: typeof import('pinia')['defineStore'];
}
export {};

📌 这样，TS 就不会报 Cannot find name 'ref' 之类的错误！

---

6. 解决常见问题

🔹 问题 1：自动导入的 API 没生效

✅ 解决方案：

• 确保 vite.config.ts 已正确配置：

  AutoImport({
    imports: ['vue', 'vue-router', 'pinia'],
    dts: 'src/auto-imports.d.ts',
  });
  

• 重启 Vite 服务器 让插件生效：

  pnpm run dev
  

---

🔹 问题 2：TypeScript 仍然报 Cannot find name 'xxx'

✅ 解决方案：

• 确保 dts 已正确配置，并且 src/auto-imports.d.ts 存在：

  dts: 'src/auto-imports.d.ts',
  

• 手动删除 src/auto-imports.d.ts，然后重启 Vite 服务器：

  rm src/auto-imports.d.ts
  pnpm run dev
  

---

🔹 问题 3：ESLint 报 no-undef

✅ 解决方案：

• 确保 eslintrc.enabled: true 已开启：

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

• 运行 pnpm run dev 让插件自动生成 .eslintrc-auto-import.json，然后在 .eslintrc.js 中引用它：

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