使用Vitest测试Vue响应式变量时$ref未定义问题求助

问题原因 #

$ref是Vue 3.3+提供的响应式语法糖，属于Vue宏的一种，通常由unplugin-auto-import插件自动导入到<script setup>中。但Vitest测试环境默认不会加载该插件的配置，导致测试时无法识别$ref，从而抛出未定义的错误。

解决方案 #

1. 确保安装依赖 #

如果项目还没安装unplugin-auto-import，先执行安装命令：

npm install unplugin-auto-import --save-dev
# 或 yarn
yarn add unplugin-auto-import -D
# 或 pnpm
pnpm add unplugin-auto-import -D

2. 配置Vite/Vitest的自动导入 #

在项目根目录的vite.config.ts（或vite.config.js）中添加unplugin-auto-import插件配置，确保包含Vue的宏：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      // 导入Vue核心API和宏
      imports: ['vue', 'vue/macros'],
      // 可选：生成类型声明文件，提升开发体验
      dts: true
    })
  ],
  test: {
    // 测试环境需配置为jsdom，模拟浏览器环境
    environment: 'jsdom',
    // 可选：启用全局测试API，无需手动import describe/test等
    globals: true
  }
})

3. 验证测试配置 #

运行测试时，确保Vitest读取到了上述配置。如果测试命令未指定配置文件，可修改package.json中的测试脚本：

{
  "scripts": {
    "test": "vitest --config vite.config.ts"
  }
}

临时替代方案（不推荐） #

如果暂时不想修改配置，可在组件中手动导入ref并使用传统写法（会丢失$ref的语法糖优势）：

<script setup>
import { ref } from 'vue'
const activeURL = ref("");
const dropdownItems = ref([]);
</script>

内容的提问来源于stack exchange，提问作者Dean Packard