Nuxt3中Vitest测试含相对路径img标签组件报错排查

Nuxt3 + Vitest 中原生标签相对URL导致测试报错的解决办法 #

在Nuxt3项目中运行Vitest时，会触发如下错误：

TypeError: Cannot read properties of undefined (reading 'cdnURL')

问题根源是组件中使用了带相对URL的原生<img>标签（图片存放在public目录，本地运行正常），移除这类标签或替换为<NuxtImg>后测试可正常执行，但项目中存在大量这类图片，无法逐一修改，因此需要不改动现有<img>标签的解决思路。

报错场景的代码示例 #

被测组件代码：

<template>
    <div>
       <img src="/images/site-logo.svg" width="204" height="24" alt="site logo" />
       <h2 class="fw-bold mt-3">
          Welcome Back!
       </h2>
    </div>
</template>

Vitest配置文件：

// vitest.config.ts
import { defineVitestConfig } from "@nuxt/test-utils/config";

export default defineVitestConfig({
    test: {
        environment: "happy-dom",
        setupFiles: "vitest-setup.ts"
    }
});

可行的解决思路 #

1. 在测试setup中Mock Nuxt的运行时配置

在vitest-setup.ts中添加对useRuntimeConfig的Mock，确保cdnURL有定义：

// vitest-setup.ts
import { vi } from 'vitest';

vi.stubGlobal('useRuntimeConfig', () => ({
  public: {
    cdnURL: '/' // 设为public目录的根路径即可
  }
}));

2. 在测试环境禁用Nuxt的图片优化插件

修改nuxt.config.ts，在测试环境下跳过Nuxt对原生<img>标签的自动处理：

// nuxt.config.ts
export default defineNuxtConfig({
  // ...其他项目配置
  hooks: {
    'vite:extendConfig': (config, { isTest }) => {
      if (isTest) {
        // 过滤掉Nuxt图片处理插件，避免触发cdnURL相关逻辑
        config.plugins = config.plugins?.filter(plugin => 
          !plugin.name?.includes('nuxt:image')
        );
      }
    }
  }
});

3. 拦截HTMLImageElement的src赋值逻辑

在测试setup中重写HTMLImageElement的src属性，绕过Nuxt的处理逻辑：

// vitest-setup.ts
import { beforeEach } from 'vitest';

beforeEach(() => {
  const OriginalImg = globalThis.HTMLImageElement;
  globalThis.HTMLImageElement = class extends OriginalImg {
    set src(value) {
      // 直接赋值原生src，不经过Nuxt的转换处理
      super.src = value;
    }
  };
});

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