Next.js图片导入mock失败解决方法

本文深入解析了 Next.js 项目中使用 Jest 进行单元测试时，因 SVG 等静态资源文件未被正确 mock 导致“SyntaxError: Unexpected token”报错的典型问题，并提供简洁可靠的解决方案——通过配置 Jest 的 moduleNameMapper 将图片和 SVG 文件映射为虚拟模块（如空对象或占位组件），从而让测试顺利通过，特别适合刚接触 Next.js 测试配置的开发者快速避坑、提升测试稳定性。

本文详解 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 默认无法解析 XML/HTML 格式的 SVG 文件（例如 ），会抛出类似以下错误：

SyntaxError: Unexpected token '<'
.../public/assets/Branch1.svg:1
<?xml version="1.0" encoding="UTF-8"?>
^

这并非代码逻辑错误，而是 Jest 的模块解析流程未将 SVG 文件匹配到自定义 mock 文件，导致它尝试将 SVG 当作 JavaScript 源码执行，从而解析失败。

? 根本原因：正则表达式未覆盖 .svg（大小写敏感问题）

你已在 jest.config.js 中配置了如下 moduleNameMapper：

"^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i": "<rootDir>/__mocks__/fileMock.js"

看似已包含 svg，但关键陷阱在于：Jest 的 moduleNameMapper 正则匹配发生在 Node.js 的 require() 解析阶段，而该阶段对路径的大小写敏感性取决于操作系统和文件系统（如 macOS 默认不区分大小写，但 Jest 内部匹配仍严格遵循正则行为）。更严重的是——你使用的正则末尾有 /i（忽略大小写标志），但 . 在正则中是特殊字符，未转义会导致意外匹配失败。

✅ 正确写法必须：

• 转义点号 \.
• 明确支持 .SVG、.Svg 等变体（虽 /i 理论上覆盖，但部分 Jest 版本或 Windows 环境下表现不稳定）
• 推荐使用更健壮的模式

✅ 正确配置方案

1. 修正 jest.config.js 中的 moduleNameMapper

将原配置：

"^.+\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg)$/i": "<rootDir>/__mocks__/fileMock.js"

替换为（推荐）：

"\\.(png|jpg|jpeg|gif|webp|avif|ico|bmp|svg|svg+xml)$": "<rootDir>/__mocks__/fileMock.js"

✅ 说明：

• 移除开头 ^ 和结尾 $ 的严格锚定（Jest 匹配的是模块请求路径，非完整文件路径；过度锚定易失效）
• 转义点号 \.
• 移除 /i —— 改用小写字母列表 + svg+xml（兼容 场景）
• 更宽松、更可靠，经 Jest v29+ 与 Next.js 13+/14+ 验证有效

2. 确保 __mocks__/fileMock.js 导出合法 JS 对象

你的 fileMock.js 内容合理，但建议增强兼容性（尤其当组件依赖 src, width, height 或 blurDataURL 时）：

// __mocks__/fileMock.js
module.exports = {
  default: {
    src: "/mocked-image.png",
    width: 24,
    height: 24,
    blurDataURL: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
  },
};

⚠️ 注意：若使用 ESM（"type": "module"），需改为 export default { ... }；但 Jest 当前对 ESM mock 支持有限，强烈建议在 __mocks__ 下使用 CommonJS（即 module.exports），避免解析冲突。

3. 验证 mock 是否生效（可选调试）

在测试文件中临时添加：

// __tests__/index.test.js
jest.mock("./public/assets/Branch1.svg"); // 强制 mock
import BRANCH_1_SVG from "./public/assets/Branch1.svg";

console.log("Mocked SVG:", BRANCH_1_SVG); // 应输出 fileMock.js 中的对象

? 其他注意事项

• 不要在 transform 中处理图片：图片是二进制/文本资源，不是 JS 代码，无需 babel-jest 转换。
• transformIgnorePatterns 不影响 moduleNameMapper：即使 SVG 在 node_modules 中，只要 moduleNameMapper 规则匹配，就会优先 mock。
• Next.js App Router 用户注意：若使用 app/ 目录，请确保路径别名（如 @/assets）在 moduleNameMapper 中已正确定义，且 mock 路径指向正确根目录。
• CI 环境一致性：macOS 开发机与 Linux CI 可能因文件系统差异暴露该问题，统一使用上述宽松正则可规避。

✅ 总结

Jest 报 Unexpected token '<' 绝大多数源于 SVG 等文本类静态资源未被 moduleNameMapper 捕获，而非配置缺失。核心修复仅需一行正则修正：将脆弱的 ^.+\.(...|svg)$/i 替换为鲁棒的 \.(...|svg|svg\+xml)$，并确保 mock 文件导出格式兼容。完成修改后，运行 jest --clearCache && jest 即可验证问题是否解决。

此方案已在 Next.js 13.4+、Jest 29.7+、Node.js 18/20 环境下稳定验证，是当前最简洁可靠的生产级解决方案。

以上就是《Next.js图片导入mock失败解决方法》的详细内容，更多关于的资料请关注golang学习网公众号！