Jest 配置详解：如何正确转译本地构建的 Design System 包-js教程-PHP中文网

Jest 配置详解：如何正确转译本地构建的 Design System 包

本文解决 Jest 默认跳过 node_modules 转译导致的 SyntaxError: Cannot use import statement outside a module 问题，重点指导如何通过 transformIgnorePatterns 精准启用对内部设计系统包（如 design-system）的 Babel/TS-Jest 转译。

本文解决 jest 默认跳过 node_modules 转译导致的 syntaxerror: cannot use import statement outside a module 问题，重点指导如何通过 transformignorepatterns 精准启用对内部设计系统包（如 design-system）的 babel/ts-jest 转译。

在企业级前端项目中，将 Design System 作为独立包（如 design-system）本地开发并直接引用，是一种常见且高效的协作模式。然而，当该包以 ES Module 形式（含 import/export）构建并输出到 dist/ 目录后，Jest 在运行测试时会因默认忽略 node_modules 下所有文件的转译而报错：

SyntaxError: Cannot use import statement outside a module
at /.../node_modules/design-system/dist/main.js:1

这是因为 Jest 的默认 transformIgnorePatterns 为 ["/node_modules/"] —— 它会完全跳过 node_modules 中所有文件的语法转换，仅依赖包自身发布的 CommonJS 版本。但你的 design-system 是内部未发布包，其 dist/main.js 保留了原生 ESM 语法（如 import $681qW$styledcomponents from "styled-components"），导致 Jest 解析失败。

✅ 正确解法：白名单式放行
在 Jest 配置中显式声明需转译的模块，而非全局关闭忽略规则。推荐在 jest.config.js（或 package.json 的 jest 字段）中添加：

module.exports = {
  // ...其他配置
  transformIgnorePatterns: [
    'node_modules/(?!design-system)' // ✅ 仅放行 design-system，其余仍被忽略
  ],
  transform: {
    '^.+\.(ts|tsx|js|jsx)$': 'ts-jest' // 或 'babel-jest'，取决于项目类型
  },
  testEnvironment: 'jsdom',
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json']
};

⚠️ 注意事项：

Yuanfang Design System

yuanfang-skills 的共享设计系统，提供 token CSS 变量、12+ 主题以及可复用的布局类型 HTML 块，供 yuanfang-html-image（以及 fu...）使用。

下载

正则表达式需精确匹配：node_modules/(?!design-system) 表示“匹配 node_modules/ 下非 design-system 开头的路径”，从而让 node_modules/design-system/ 进入转译流程。若包名为 @company/design-system，应改为 node_modules/(?!@company\/design-system)（注意转义斜杠）。
避免过度放行：切勿使用 "node_modules/"（空数组）或过于宽泛的模式（如 node_modules/(?!.*-ui)），否则会大幅拖慢测试启动速度，并可能引发第三方包兼容性问题。
TypeScript 项目请用 ts-jest：若 design-system 使用 TypeScript 编写，确保 transform 指向 ts-jest，并在根目录存在有效 tsconfig.json；Babel 用户则需配置 @babel/preset-env 支持 ES modules。
配合 moduleNameMapper 提升可维护性（可选）：若 design-system 存在别名路径（如 @ds/components），建议同步配置 moduleNameMapper 映射真实路径，避免相对路径硬编码。

? 扩展建议：
对于多包设计系统（如 @myorg/core、@myorg/react），可扩展正则为：

transformIgnorePatterns: [
  'node_modules/(?!(@myorg\/core|@myorg\/react|design-system))'
]

最终效果：Jest 将对 node_modules/design-system/ 内所有 .js/.ts 文件执行转译，成功解析 ESM 语法，使组件测试（如 render(<tab></tab>)）顺利通过，同时保持对其他第三方库的高效处理。这是兼顾开发便利性与测试稳定性的最佳实践。