Nuxt3+Vitest测试composables报ref未定义 如何自动导入Vue响应式API

Nuxt 3 内置的自动导入能力是框架层实现的代码转换逻辑，仅在 Nuxt 运行/构建流程中生效。直接使用原生 Vitest 执行测试用例时，既不会加载 Nuxt 的转换规则，也没有配置对应 Vitest 侧的自动导入能力，因此源码中未手动引入的computed、unref等 Vue API 会直接抛出未定义错误。
之前单独添加@vitejs/plugin-vue无法解决问题，是因为该插件仅负责处理 Vue 单文件组件编译，不包含任何自动导入相关逻辑。

二选一即可，优先推荐方案1，和项目运行时行为完全对齐，不需要额外维护配置。

方案1：使用官方 Nuxt Vitest 适配模块（推荐） #

官方模块会自动同步 Nuxt 项目的别名配置、自动导入规则、运行环境，避免测试环境和实际运行环境出现行为差异。

• 安装依赖

npm install -D @nuxt/test-utils vitest @vue/test-utils

• 在nuxt.config.ts中注册测试模块

export default defineNuxtConfig({
  // 保留原有其他配置
  modules: [
    // 保留原有其他模块
    '@nuxt/test-utils/module'
  ]
})

• 重写vitest.config.ts，使用官方导出的配置方法包裹自定义配置

import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './test/setupUnit.ts',
    exclude: [
      '**/node_modules/**',
      '**/dist/**',
      '**/cypress/**',
      '**/.{idea,git,cache,output,temp}/**'
    ]
  }
})

方案2：手动配置 Vitest 自动导入规则 #

如果不想引入官方测试模块，可以通过自动导入插件手动对齐 Nuxt 的导入规则：

• 安装依赖

npm install -D unplugin-auto-import @vitejs/plugin-vue

• 修改vitest.config.ts添加插件配置

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

export default defineConfig({
  plugins: [
    Vue(),
    AutoImport({
      // 对齐Nuxt默认自动导入的API来源，后续如果有自定义composables目录也可以在这里加规则
      imports: ['vue', '@vueuse/core'],
      dts: false
    })
  ],
  resolve: {
    alias: {
      '~': '.',
      '~~': './',
      '@@': '.',
      '@@/': './',
      'assets': './assets',
      'public': './public',
      'public/': './public/'
    }
  },
  test: {
    globals: true,
    setupFiles: './test/setupUnit.ts',
    environment: 'jsdom',
    deps: { inline: [/@nuxt\/test-utils-edge/] },
    exclude: [
      '**/node_modules/**',
      '**/dist/**',
      '**/cypress/**',
      '**/.{idea,git,cache,output,temp}/**'
    ]
  }
})

• 原有vitest.config.ts的exclude规则中写了'test/**/**.spec.ts'，会把test目录下所有测试用例全部排除，Vitest根本扫不到这些文件，必须删掉这行配置。
• 现有测试用例本身存在逻辑错误：传入的校验参数是0，按照写的x > 0规则校验不通过，当前写的expect(isValid.value).toBe(true)断言会执行失败，需要把入参改成大于0的数值，或者调整断言匹配错误提示。

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