Scala.js 项目中使用 ESModule 输出格式的注意事项

问题背景

在 Scala.js 项目中，开发者可以通过配置将代码编译为 ESModule 格式。然而，当使用 sbt test 命令运行测试时，可能会遇到 SyntaxError: Unexpected token 'export' 的错误。这是因为 Node.js 对 ESModule 的支持方式与 CommonJS 模块不同。

根本原因分析

Node.js 对 ESModule 的处理有以下特点：

1. 默认情况下，Node.js 会尝试将 .js 文件作为 CommonJS 模块加载
2. 当遇到 ESModule 语法（如 export）时，会导致语法错误
3. Node.js 需要通过文件扩展名或 package.json 配置来明确指定模块类型

解决方案

要让 Scala.js 生成的 ESModule 代码在 Node.js 环境中正常运行，需要进行以下配置调整：

1. 修改输出文件扩展名为 .mjs，这是 Node.js 识别 ESModule 的标准方式
2. 更新 Scala.js 链接器配置，指定正确的输出模式

具体配置示例如下：

import org.scalajs.linker.interface.OutputPatterns

scalaJSLinkerConfig ~= {
  // 启用 ESModule 输出
  _.withModuleKind(ModuleKind.ESModule)
   // 使用 .mjs 扩展名
   .withOutputPatterns(OutputPatterns.fromJSFile("%s.mjs"))
}

深入理解

模块系统差异

1. CommonJS:

   • Node.js 传统模块系统
   • 使用 require() 和 module.exports
   • 同步加载模块

2. ESModule:

   • JavaScript 标准模块系统
   • 使用 import 和 export
   • 支持静态分析和异步加载

为什么需要特殊配置

Node.js 为了保持向后兼容性，需要明确区分两种模块类型。通过使用 .mjs 扩展名，可以明确告知 Node.js 该文件应该作为 ESModule 处理，从而避免语法错误。

最佳实践

1. 对于新项目，建议直接使用 ESModule 作为默认模块格式
2. 如果项目需要同时支持浏览器和 Node.js 环境，确保测试配置正确处理模块类型
3. 考虑在 CI/CD 流程中添加对模块类型的验证步骤

总结

在 Scala.js 项目中使用 ESModule 输出格式时，正确处理文件扩展名是关键。通过配置 .mjs 扩展名，可以确保生成的代码在 Node.js 环境中正确执行。这一解决方案不仅适用于测试场景，也适用于任何需要在 Node.js 中运行 Scala.js 代码的情况。