vue3+ts在uniapp项目中实现自动导入 ref 和 reactive

前言

在使用 Vue3 +ts写代码时，ref、reactive、computed 几乎是"日用品"。但问题也来了------每个页面都要手动写

javascript 复制代码

import { ref, reactive } from 'vue'

写得多了你就会开始怀疑人生：

"Vue3 都 2026年了，为什么还不能自动 import？"

于是，我把目光投向了神器 unplugin-auto-import。

本以为是"安装即用"，结果一顿操作猛如虎，Vite 启动直接原地爆炸。

后面翻了一圈报错栈，才发现：

👉 不是我姿势不对，而是 unplugin-auto-import 新版本和 uni-app + Vite 不兼容。

下面就是完整的踩坑 → 定位 → 解决方案。

一、安装插件（别急，坑就在这）

官方文档里的安装方式是这样的：

javascript 复制代码

pnpm i unplugin-auto-import -D
# 或
npm i unplugin-auto-import -D
# 或
yarn add unplugin-auto-import -D

如果你直接这样装，在 uni-app + Vite 项目中，大概率会直接报错。

错误类似这样：

Error [ERR_REQUIRE_ESM]: require() of ES Module unimport/dist/index.mjs not supported

简单翻译一下就是：

"你在用 CommonJS，而我已经是 ESM-only 了，咱俩不合适。"

也就是说：

默认安装的是 unplugin-auto-import@20.x

它依赖的 unimport@5.x 是纯 ESM

而 uni-app 的 Vite CLI 仍然是 CommonJS 加载链

👉 结构性不兼容，神仙也救不了

二、正确姿势：安装兼容版本

既然是版本问题，那就------选一个能活的版本。

1️⃣ 先查看所有可安装版本

javascript 复制代码

pnpm view unplugin-auto-import versions

你会看到一长串版本号。
2️⃣ 结论先行（直接抄）
在 uni-app + Vite 项目中，最稳妥的版本是：

javascript 复制代码

pnpm add -D unplugin-auto-import@0.18.6

为什么是它？

0.18.6 是 0.x 时代的最后一个稳定版本

使用的是 CommonJS 友好依赖

不会引入 unimport@5.x 这种 ESM-only 雷区

已被大量 uni-app 项目实战验证

一句话总结：

19.x / 20.x 是给"纯 Vite 项目"用的，uni-app 请止步于 0.18.6。

三、配置插件（这一步没什么坑）

安装完成后，在 vite.config.ts 中引入并配置插件：

javascript 复制代码

import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import AutoImport from "unplugin-auto-import/vite";

export default defineConfig({
  plugins: [
    uni(),
    AutoImport({
      imports: [
        "vue",      // 自动导入 ref、reactive、computed 等
        "uni-app",  // 自动导入 uni 相关 API
      ],
    }),
  ],
});

到这里：

项目能正常启动

.vue 文件里不写 import { ref } from 'vue'

运行时不会报错

但------

你很快会发现一个"灵异现象"。

四、为什么编辑器还在骂我？（ts(2304)）

在 .vue 文件里写：

javascript 复制代码

const title = ref('Hello')

页面能跑，但 VS Code 却提示：

❌ 找不到名称"ref" ts-plugin(2304)

别慌，这不是插件失效，而是------

Auto Import 只负责"运行时注入 import"，

TypeScript 还不知道 ref 是全局变量。

五、关键一步：配置 auto-imports.d.ts

unplugin-auto-import 会自动生成一个类型声明文件：

javascript 复制代码

auto-imports.d.ts

你要做的，就是明确告诉 TypeScript：这个文件你得看。
在 tsconfig.json 中这样配置：

javascript 复制代码

{
  "extends": "@vue/tsconfig/tsconfig.json",
  "compilerOptions": {
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "lib": ["esnext", "dom"],
    "types": [
      "@dcloudio/types",
      "vite/client",
      "uview-plus/types",
      "@uni-helper/uni-app-types",
      "@uni-helper/uni-ui-types"
    ]
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "auto-imports.d.ts"
  ]
}

⚠️ 这一行是灵魂：

javascript 复制代码

"auto-imports.d.ts"

少了它，TS 永远不认识 ref。

配置完成后：
重新运行项目

六、最终效果

现在你可以在 .vue 里安心写：

javascript 复制代码

<script setup lang="ts">
const title = ref('Hello')
const state = reactive({ count: 0 })
</script>

✔ 不用手写 import

✔ 不报运行错误

✔ 编辑器不再阴阳怪气

✔ 心情指数 +50%

总结（给后来人的一句忠告）

在 uni-app + Vite 项目中使用 unplugin-auto-import：

不要装最新版本

0.18.6 是安全上限

别忘了把 auto-imports.d.ts 加进 tsconfig

否则你会以为是自己不会配，其实是版本在背刺你。

如果你之后还想配 Components 自动引入、uView，那又是另一个坑了。