使用Mocha+Babel测试Node.js应用 引入ES模块依赖bpmn-js报错

基础环境说明 #

• Node.js v14.15.4
• Mocha v8.2.1
• Babel 依赖版本：@babel/core v7.12.10、@babel/register v7.12.10、@babel/preset-env v7.12.11
• 引入的业务依赖：bpmn-js v8.2.0

问题现象 #

完成Babel与Mocha的基础接入后，项目本地编写的ES模块测试可正常运行；当业务代码引入bpmn-js依赖后，执行测试直接抛出SyntaxError: Unexpected token 'export'，错误定位到node_modules/bpmn-js/index.js的ES导出语句。

问题根因 #

@babel/register 默认内置规则为忽略所有node_modules路径下的文件编译，设计逻辑是默认第三方发布的依赖已完成多环境格式兼容，不需要重复转译。但bpmn-js v8.2.0 的主入口文件采用原生ES模块导出语法，而当前Node.js v14处于CommonJS默认运行模式，无法直接解析export关键字，因此触发语法错误。

操作步骤 #

• 自定义@babel/register编译规则，将需要转译的第三方依赖从默认忽略列表中排除
  在项目根目录新建babel-register.js，写入如下配置：

  require('@babel/register')({
    // 覆盖默认忽略规则：匹配所有node_modules路径，仅放行指定的ES格式依赖
    ignore: [
      /node_modules\/(?!(bpmn-js|@bpmn-io|diagram-js)\/).*/
    ],
    extensions: ['.js']
  });
  

• 修改package.json中的测试启动命令，替换原有的直接引入@babel/register的写法
  原测试脚本：

  "test": "mocha --require @babel/register index.test.js"
  

  修改为：

  "test": "mocha --require ./babel-register.js index.test.js"
  

• 调整@babel/preset-env的转译目标，确保编译输出为CommonJS格式，适配Node.js v14的运行要求
  修改babel.config.json配置：

  {
    "presets": [
      [
        "@babel/preset-env",
        {
          "targets": {
            "node": "14.15.4"
          },
          "modules": "commonjs"
        }
      ]
    ]
  }
  

注意事项 #

• 不要将整个node_modules目录纳入编译范围，会大幅增加测试启动耗时，仅将实际用到、存在原生ES导出语法的依赖加入规则白名单即可
• 后续引入其他存在同类语法兼容问题的第三方依赖时，只需将对应包名追加到忽略规则的白名单括号内，无需调整其他配置

内容的提问来源于stack exchange，提问作者sensati0n