ScalaJS项目配置ES模块时遇到的Node.js兼容性问题解析

在ScalaJS项目中，当开发者尝试同时配置Scala和ScalaJS跨平台支持时，可能会遇到一个典型的测试执行错误。本文将从技术原理角度剖析该问题的成因及解决方案。

问题现象

开发者在项目中同时配置JVM和JS平台支持后，执行测试时出现以下关键错误：

1. Node.js运行时抛出警告：要求设置"type": "module"或使用.mjs扩展名
2. 具体报错显示SyntaxError: Cannot use import statement outside a module
3. 即使用户显式设置scalaJSStage := FullOptStage，模块生成行为仍不符合预期

技术背景

1. ES模块规范：现代JavaScript支持ES模块语法（import/export），这是ECMAScript标准的一部分
2. Node.js实现差异：Node.js对ES模块的实现需要特殊配置（不同于浏览器环境）
3. ScalaJS输出策略：ScalaJS默认生成符合ECMAScript标准的模块文件，不特定针对Node.js的.mjs约定

问题根源

该问题的本质是运行环境配置与编译输出模式不匹配：

• ScalaJS配置为输出ES模块（使用import/export语法）
• 但Node.js默认以CommonJS模式加载.js文件，无法识别其中的ES模块语法
• 文件扩展名.js在Node.js中默认不被视为ES模块

解决方案

1. 配置Node.js识别ES模块：

   • 在项目根目录添加package.json并设置"type": "module"
   • 或重命名输出文件为.mjs扩展名

2. 调整ScalaJS编译选项：

   scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) }
   

   改为输出CommonJS模块格式（兼容Node.js默认行为）

3. 测试环境配置：

   Test / jsEnv := new org.scalajs.jsenv.nodejs.NodeJSEnv(
     org.scalajs.jsenv.nodejs.NodeJSEnv.Config()
       .withArgs(List("--experimental-vm-modules"))
   

   显式启用Node.js的ES模块支持

最佳实践建议

1. 跨平台项目应明确区分不同目标的模块系统需求
2. 在CI环境中确保测试运行器的Node.js版本支持ES模块
3. 对于库项目，建议优先采用CommonJS模块格式保证最大兼容性
4. 仔细阅读ScalaJS文档中关于模块系统的说明，理解不同ModuleKind的适用场景