本文详解 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)$/i 替换为鲁棒的 .(...|svg|svg+xml)$，并确保 mock 文件导出格式兼容。完成修改后，运行 jest --clearCache && jest 即可验证问题是否解决。
此方案已在 Next.js 13.4+、Jest 29.7+、Node.js 18/20 环境下稳定验证，是当前最简洁可靠的生产级解决方案。
