Nuxt3使用Vitest编写单元测试时报Failed to load component错误

Failed to load component 报错核心原因是未适配Nuxt3的运行时特性：纯Vitest默认配置无法识别Nuxt的自动组件注册、#开头的内置别名、自动导入API、内置组件（如<NuxtLink> <ClientOnly>），直接按Vue项目的方式写测试就会触发组件加载失败。以下是可直接复用的落地步骤：

1. 安装对应依赖 #

不要混用Nuxt2版本的测试工具，直接安装适配Nuxt3的官方包：
pnpm add -D @nuxt/test-utils vitest @vitejs/plugin-vue jsdom
如果偏好更快的运行速度，可把jsdom替换为happy-dom，对应后续配置里的environment值改成happy-dom即可

2. 编写Vitest配置文件 #

在项目根目录新建vitest.config.ts，必须配置Nuxt专属别名、DOM环境、setup入口：

import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath } from 'node:url'

export default defineConfig({
  plugins: [vue()],
  test: {
    environment: 'jsdom',
    setupFiles: [fileURLToPath(new URL('./tests/setup.ts', import.meta.url))],
    alias: {
      '~': fileURLToPath(new URL('./', import.meta.url)),
      '@': fileURLToPath(new URL('./', import.meta.url)),
      '#imports': fileURLToPath(new URL('./.nuxt/imports.d.ts', import.meta.url)),
      '#components': fileURLToPath(new URL('./.nuxt/components.d.ts', import.meta.url)),
      '#app': fileURLToPath(new URL('./node_modules/nuxt/dist/app/index.mjs', import.meta.url))
    },
    include: ['tests/**/*.test.ts', 'components/**/*.test.ts'],
    deps: {
      inline: [/nuxt/]
    }
  }
})

3. 编写全局测试Setup文件 #

在项目根目录新建tests/setup.ts，统一处理全局组件注册、Nuxt内置API Mock，从根源解决组件找不到的问题：

import { config } from '@vue/test-utils'
import { vi } from 'vitest'
import registeredComponents from '#components'

// 全局注册所有Nuxt自动扫描的业务组件、内置组件
Object.entries(registeredComponents).forEach(([compName, compInstance]) => {
  config.global.components[compName] = compInstance
})

// Mock Nuxt内置运行时API，按自己项目的实际配置补全默认值即可
vi.mock('#app', () => ({
  useRuntimeConfig: () => ({
    public: {
      apiBase: 'http://test-api.local'
    }
  }),
  useRoute: () => ({
    path: '/test',
    params: {},
    query: {}
  }),
  useRouter: () => ({
    push: vi.fn(),
    replace: vi.fn(),
    back: vi.fn()
  }),
  useHead: vi.fn(),
  definePageMeta: vi.fn(),
  navigateTo: vi.fn()
}))

// Mock Nuxt自动导入的API
vi.mock('#imports', async (importOriginal) => {
  const actual = await importOriginal() as any
  return {
    ...actual,
    useFetch: vi.fn(() => ({
      data: ref(null),
      pending: ref(false),
      error: ref(null),
      refresh: vi.fn()
    })),
    useAsyncData: vi.fn(() => ({
      data: ref(null),
      pending: ref(false),
      error: ref(null),
      refresh: vi.fn()
    })),
    useState: vi.fn((key: string, init?: () => any) => ref(init?.()))
  }
})

// 按需Mock浏览器专属API，比如localStorage
Storage.prototype.getItem = vi.fn(() => null)
Storage.prototype.setItem = vi.fn()

4. 测试用例正确写法 #

优先使用@nuxt/test-utils提供的mountSuspended方法挂载组件，会自动注入Nuxt运行时上下文，不需要重复处理异步组件、Suspense加载问题：

// tests/components/MyBanner.test.ts
import { describe, it, expect } from 'vitest'
import { mountSuspended } from '@nuxt/test-utils/runtime'
// 局部注册的组件可手动导入，全局自动注册的组件无需导入
import MyBanner from '@/components/MyBanner.vue'

describe('MyBanner组件', () => {
  it('正常渲染传入的标题', async () => {
    const wrapper = await mountSuspended(MyBanner, {
      props: {
        title: '活动通知'
      }
    })
    expect(wrapper.find('.banner-title').text()).toBe('活动通知')
  })
})

5. 前置操作与脚本配置 #

1. 第一次跑测试前，必须执行一次pnpm nuxt prepare，该命令会生成.nuxt目录下的组件映射、自动导入声明文件，否则别名指向的文件不存在会直接报组件加载失败。后续新增组件、修改自动导入规则后，重新执行一次该命令即可。
2. 在package.json中添加测试脚本：

{
  "scripts": {
    "test": "vitest dev",
    "test:run": "vitest run"
  }
}

常见报错排查清单 #

• 报Failed to resolve import "#components"/"#imports"：没执行nuxt prepare，或者vitest.config里的别名配置路径错误
• 报Failed to resolve component "NuxtLink"/自定义组件名：setup文件里没有全局注册自动扫描的组件，或者没执行nuxt prepare导致组件映射表未更新
• 组件挂载时抛DOM相关错误：检查test.environment是否配置为jsdom/happy-dom，node默认环境没有DOM API
• 组件内引用第三方Nuxt模块报加载失败：在setup文件里补对应模块的Mock，或者在vitest.config的deps.inline里加入对应模块名做转译

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