Next.js + Jest 图片导入 mock 失败的根因与正确配置方案

本文详解 Next.js 项目中 Jest 测试因 SVG 等静态资源未被正确 mock 导致的 SyntaxError: Unexpected token '

本文详解 next.js 项目中 jest 测试因 svg 等静态资源未被正确 mock 导致的 `syntaxerror: unexpected token '

在 Next.js 项目中集成 Jest 进行组件测试时，直接导入 SVG、PNG 等静态资源（如 import Logo from '@/assets/logo.svg'）会触发 Jest 解析原始文件内容——而 SVG 是 XML 格式文本，以 或

? 问题定位：正则表达式未覆盖 SVG（关键陷阱）

你配置中的这一行：

"^.+\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i"

看似包含 svg，但实际无法匹配 .svg 文件路径。原因在于：

• ^.+\. 要求路径中必须存在 至少一个字符 + 字面量点号（如 logo.svg 中的 o.）；
• 但当文件位于 public/assets/Branch1.svg 时，Jest 内部解析的模块请求路径可能是 ./public/assets/Branch1.svg —— 此时 ^ 锚定开头，.+ 匹配 ./public/assets/Branch1，\. 匹配最后一个点，随后 (png|...|svg) 尝试匹配 svg，看似合理。

⚠️ 真正的问题在于：Jest 的 moduleNameMapper 使用的是 Node.js 的 require.resolve() 语义，对 public/ 下的静态资源处理特殊。Next.js 推荐将图片等静态资源放在 public/ 目录下（通过 /assets/logo.svg URL 访问），而非 import 方式引入。但若你确需 import（例如用作 next/image 的 src），则该导入路径实际指向的是文件系统中的原始 SVG 文件，而你的正则未被触发，因为：

• Jest 在匹配时可能对 public/ 路径做了特殊处理；
• 更常见的是：/i 修饰符虽启用忽略大小写，但某些 Jest 版本（尤其搭配 ESM）对正则兼容性不佳，且 ^ 和 $ 在模块路径匹配中并非总是按字面意义工作。

✅ 正确写法应更宽松、更鲁棒，推荐使用：

紫东太初

中科院和武汉AI研究院推出的新一代大模型

下载

// jest.config.js
moduleNameMapper: {
  // ✅ 正确：移除 ^$ 锚点，用 .* 避免路径结构依赖，明确包含 svg
  "\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$": "<rootDir>/__mocks__/fileMock.js",
  // 其他映射保持不变...
}

✅ 完整可运行配置示例

1. 创建 __mocks__/fileMock.js（ESM 兼容写法）

// __mocks__/fileMock.js
// 注意：若 package.json 中有 "type": "module"，此处必须用 export default
export default {
  src: '/mock-image.png',
  height: 24,
  width: 24,
  blurDataURL: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==',
};

2. 更新 jest.config.js（关键修正）

// jest.config.js
export default {
  // ...其他配置保持不变
  moduleNameMapper: {
    "^.+\.module\.(css|sass|scss)$": "identity-obj-proxy",
    "^.+\.(css|sass|scss)$": "<rootDir>/__mocks__/styleMock.js",

    // ✅ 重点修正：移除 ^ $，添加 svg，确保匹配所有目标扩展名
    "\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$": "<rootDir>/__mocks__/fileMock.js",

    "^@/components/(.*)$": "<rootDir>/components/$1",
    "^@/pages/(.*)$": "<rootDir>/pages/$1",
  },
  // ...其余配置
};

3. 验证测试用例（确保 mock 生效）

// __tests__/ImageComponent.test.tsx
import { render, screen } from '@testing-library/react';
import ImageComponent from '@/components/ImageComponent';

test('renders mocked image with correct props', () => {
  render(<ImageComponent />);
  const img = screen.getByRole('img');
  // fileMock.js 返回的对象属性会被透传
  expect(img).toHaveAttribute('src', '/mock-image.png');
  expect(img).toHaveAttribute('height', '24');
});

⚠️ 注意事项与最佳实践

• 优先使用 public/ 目录 + URL 引用：Next.js 官方强烈建议将静态资源（SVG/PNG）放入 public/，通过 /assets/icon.svg 这类 URL 使用，而非 import。这既避免 mock 复杂性，又符合 SSR/SSG 优化逻辑。
• ESM 项目需严格匹配导出语法：若 package.json 含 "type": "module"，__mocks__/fileMock.js 必须用 export default，不可用 module.exports。
• 清除缓存再测试：修改配置后务必运行 npx jest --clearCache，否则旧缓存可能导致 mock 不生效。
• 调试技巧：在 fileMock.js 中加入 console.log('fileMock loaded')，若控制台无输出，说明正则未命中；若有输出但报错依旧，则检查 mock 返回值是否符合 next/image 所需 shape（src, width, height, blurDataURL）。

通过修正正则表达式并采用上述配置，即可彻底解决 Jest 解析 SVG 报 Unexpected token '