Nuxt项目运行Vitest测试时路径别名@无法解析如何解决

你在nuxt.config.ts里配置的vite别名仅在Nuxt开发服务、生产构建流程中生效，Vitest是独立运行的测试工具，默认不会主动读取Nuxt配置文件内的规则，因此无法识别@路径别名，触发模块找不到的报错。

以下两种方案都可以解决问题，优先选第一种：

方案1：使用Nuxt官方测试工具（零重复配置，推荐） #

Nuxt官方提供的测试工具包会自动同步项目内所有路径别名、Nuxt内置规则、环境配置，不需要手动重复写配置：

• 第一步安装依赖：

npm i -D @nuxt/test-utils vitest @vitejs/plugin-vue

• 第二步在项目根目录新建vitest.config.ts，直接引入Nuxt提供的Vitest预设：

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

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    // 可以在这里加你需要的其他Vitest配置，比如测试文件匹配规则、覆盖率配置等
  }
})

• 第三步在package.json里添加测试执行脚本：

{
  "scripts": {
    "test": "vitest"
  }
}

配置完成后直接执行npm run test即可，包括@在内的所有Nuxt默认别名、你自定义的别名都会自动在测试文件中生效，不需要额外维护。

方案2：手动同步别名配置（不引入官方测试工具的场景） #

如果不想引入额外的官方测试依赖，可以直接在Vitest独立配置文件中手动写死别名规则：

• 在项目根目录新建vitest.config.ts，添加resolve.alias配置：

import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './')
      // 注意：如果你的业务代码都放在src目录下，上面的路径改成'./src'即可
      // 有其他自定义别名也可以在这里同步添加
    }
  },
  test: {
    // 其他Vitest配置
  }
})

如果你用TypeScript开发，还要同步在tsconfig.json的compilerOptions.paths字段添加对应映射，否则TS会报类型找不到的错误：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
      // 代码在src目录的话改成["./src/*"]
    }
  }
}

避坑提醒 #

• 别名配置修改后必须完全重启Vitest进程，配置改动不会触发热更新，不重启会一直报解析错误
• Nuxt3默认已经内置了@指向项目根目录（存在src目录时自动指向src）的别名，不需要你在nuxt.config.ts里重复写vite.resolve.alias规则，重复配置反而可能因为path引用错误触发构建问题
• 不要尝试让Vitest直接读取nuxt.config.ts里的配置，Nuxt的配置需要经过框架本身的解析流程才能拿到最终值，直接读取会出现配置不一致的问题

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