当你在 Webpack 项目里为 React、Vue 组件编写 Jest 单元测试时，组件源码经常会引入样式和图片，例如 import './index.css' 和 import avatar from './avatar.png'。Jest 运行在 Node.js 环境，既没有 Webpack 的 loader 链，也不会解析 .css 文件，因此一旦执行测试就会抛出 SyntaxError。要解决这个问题，需要显式告诉 Jest 怎样处理这些静态资源。
核心思路并不复杂：Jest 并不需要像 Webpack 那样真实编译 CSS 或压缩图片，大多数情况下只需要把这些导入路径替换成一个可用的字符串即可。下面会从报错原因、映射配置、transform 方案以及 Webpack 别名同步几个层面展开。
一、为什么 Jest 会报 SyntaxError
Jest 默认使用 babel-jest 来转换 JavaScript 和 JSX，但遇到 import './index.css' 时，它不会触发任何样式 loader。Jest 把 .css 文件当成普通 JavaScript 模块读取，CSS 中的 class 选择器、大括号和冒号对 JavaScript 解析器来说是非法语法，于是抛出 SyntaxError: Unexpected token '.' 这样的错误。
图片和字体的问题略有不同。Node 环境本身可以读取 Buffer，但 ES module 的 import 语法预期导入的是一个可执行模块，而不是二进制文件。如果直接 import 一张 png，Jest 通常会提示 Cannot find module 或 Unexpected character。因此需要把这些资源映射成 Jest 能理解的 JavaScript 值。
理解了这个背景，就能明确后续配置的目标：不是让 Jest 真正处理样式和图片，而是让所有静态资源 import 都返回一个对测试有意义的字符串或对象。
二、使用 moduleNameMapper 映射 CSS 与图片
最常用的方案是在 Jest 配置中加入 moduleNameMapper。它可以像 Webpack 的 alias 一样，用正则匹配模块路径，并替换成另一个模块。对于普通 CSS 和 CSS Modules，可以安装 identity-obj-proxy，它会把类名映射成相同名称的字符串。
module.exports = {
moduleNameMapper: {
'\\.(css|less|scss|sass)$': 'identity-obj-proxy',
'\\.(jpg|jpeg|png|gif|svg|webp)$': '<rootDir>/__mocks__/fileMock.js',
},
};
上面的配置中，<rootDir> 表示项目根目录。还需要创建 fileMock.js，内容只需导出一个字符串，例如 module.exports = 'test-file-stub';。这样组件里 import 的图片在测试中都会被替换成这个固定字符串。
对于 CSS Modules 项目，使用 identity-obj-proxy 后，可以断言某个类名是否存在。比如组件导入了 styles.primary，测试中可以写 expect(styles.primary).toBe('primary')。它不会返回真实打包后的哈希类名，但对单元测试来说已经足够稳定和快速。
三、transform 方案适合需要读取文件内容的场景
如果测试中不仅需要静默跳过静态资源，还想读取 SVG 文件内容、验证某个 JSON 或者对 CSS 做快照，可以改用 transform 配置。Jest 的 transform 会在模块加载前对文件内容做转换，像 jest-transform-stub 这类包可以返回空字符串或固定内容。
通过 transform 处理静态资源时，配置通常写成这样：
module.exports = {
transform: {
'^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
'^.+\\.(css|scss|less)$': 'jest-transform-stub',
'^.+\\.(jpg|jpeg|png|gif|svg)$': 'jest-transform-stub',
},
};
transform 和 moduleNameMapper 最好不要同时命中同一类文件，因为两者的执行顺序可能带来意料之外的替换结果。通常的实践是：只是让测试跑通，优先用 moduleNameMapper；如果确实要拿到文件内容做断言，再为特定目录单独配置 transform。对大多数组件测试来说，桩字符串已经足够，transform 往往用于工具函数或图标库的边界场景。
四、同步 Webpack 别名与 CSS Modules 测试实践
很多 Webpack 项目配置了路径别名，例如把 src 目录映射为 @。组件里写 import Button from '@/components/Button' 时，Webpack 能正常解析，但 Jest 不知道这个别名规则，会报 Cannot find module '@/components/Button'。解决办法是在 Jest 的 moduleNameMapper 中镜像一份同样的规则。
module.exports = {
moduleNameMapper: {
'^@/(.*)$': '<rootDir>/src/$1',
'\\.(css|less|scss|sass)$': 'identity-obj-proxy',
'\\.(jpg|jpeg|png|gif|svg)$': '<rootDir>/__mocks__/fileMock.js',
},
};
这段配置把 import 路径中的 @/ 替换为 <rootDir>/src/，$1 保留后面的路径。Webpack 里的 alias 修改后，测试配置也要同步调整，否则测试环境会与真实构建出现不一致。
CSS Modules 的测试还有一个实用细节：如果组件依赖 styles 对象中的多个类名，identity-obj-proxy 返回的字符串足以通过断言，但如果你想验证真实 CSS 文件里的类名是否匹配，需要额外引入 CSS 解析工具，这在大多数项目中并不必要。保持测试聚焦组件行为，而不是构建产物，会让维护成本更低。
当项目同时存在普通 CSS 和 CSS Modules 时，可以用文件命名约定区分映射规则，例如把所有 .module.css 映射到 identity-obj-proxy，普通 .css 映射到空模块。这样测试结果更接近实际开发中的模块边界。
五、常见报错与排查清单
配置完成后，如果组件测试仍然报错，可以按下面的顺序排查。首先确认 jest.config.js 的配置是否真的被读取，其次是正则是否写错。很多开发者会把 '\\.(css|less)$' 写成 '\.(css|less)$'，导致匹配失败，因为字符串里反斜杠需要转义。
第二类常见问题是图片路径未匹配。比如项目里使用了 webp 或 ttf 字体，但映射正则里漏掉了这些扩展名。建议把图片、音频、字体等二进制资源统一到一个正则里，避免测试时突然出现 Unexpected character 错误。第三类是别名不生效：Webpack 的 alias 改了，但 Jest 的 moduleNameMapper 没有同步，会直接找不到模块。
最后，如果仍然出现 transform 相关报错，检查是否同时启用了 moduleNameMapper 和 transform 处理同一类文件。建议二选一：要么统一用映射，要么统一用 transform，并保持规则清晰。这样静态资源处理链路就不会干扰测试本身的稳定性。