在 javascript 项目中配合使用 es modules (esm) 和 babel,核心做法是配置 @babel/preset-env 并设置 modules: 'auto'。这样 babel 会根据目标运行环境自动决定是否需要将 esm 语法转换为 commonjs (cjs),若目标环境原生支持 esm 则保留原样,否则进行转换。

Babel 如何根据环境决定是否转换 ESM
Babel 通过 @babel/preset-env 的 modules 选项控制模块系统的转换行为。当设置为 'auto' 时,Babel 会检查配置的 targets(如浏览器版本或 Node.js 版本)。如果目标环境不支持 import/export,Babel 会将它们转换为 require/module.exports;如果支持,则保持 ESM 格式不变,从而利用 Tree Shaking 等现代打包优势。

{
"presets": [
[
"@babel/preset-env",
{
"modules": "auto",
"targets": ">= 10"
}
]
]
}
上述配置中,"modules": "auto" 是关键。假设我们有一个简单的源文件 index.js:
// index.js
export const add = (a, b) => a + b;
import { add } from './utils';
console.log(add(1, 2));
如果 targets 设为 >= 10(Node.js 10+ 或现代浏览器),输出仍为 ESM。如果 targets 设为 ie 11,输出将变为 CJS:
// 转换后 (CJS)
exports.add = function(a, b) { return a + b; };
var utils = require('./utils');
console.log(utils.add(1, 2));
如何处理第三方库中的 ESM 依赖
当项目依赖包含 ESM 语法的第三方库时,直接引入可能导致构建失败或运行时错误。解决方法是使用 @rollup/plugin-babel 或 @babel/preset-env 配合 browserslist 确保所有代码都被正确转译。对于纯 Node.js 环境,可以使用 esm 包或设置 type: "module" 并在 package.json 中指定入口点。

// package.json
{
"name": "my-project",
"version": "1.0.0",
"type": "module",
"dependencies": {
"some-esm-lib": "^1.0.0"
},
"devDependencies": {
"@babel/core": "^7.20.0",
"@babel/preset-env": "^7.20.0"
}
}
在 Node.js 环境中,如果 package.json 设置了 "type": "module",则所有 .js 文件默认被视为 ESM。此时,如果第三方库是 CJS,Node.js 会自动处理互操作性。但如果第三方库也是 ESM,且你的构建工具(如 Webpack)未正确处理,可能需要配置 resolve.mainFields 指向正确的入口文件。
基于 Babel 配置中 modules 参数的具体影响
在 Babel 配置中,modules 参数除了 'auto' 外,还可以显式设置为 false 或 true。当设置为 false 时,Babel 永远不会转换模块语法,即使目标环境不支持 ESM。这通常用于与 Rollup 或 Webpack 4/5 等现代打包器配合,由打包器负责模块解析和优化。
// babel.config.js
module.exports = {
presets: [
['@babel/preset-env', {
modules: false, // 强制不转换模块
targets: '> 0.25%, ie 11'
}]
]
};
在这种配置下,无论目标环境如何,输出的代码都将保留 import/export 语法。如果直接使用 Node.js 运行此代码而不经过打包器,且 Node.js 版本低于 12(或未启用实验性 ESM),将会抛出 SyntaxError。因此,modules: false 适用于构建流程中包含现代打包器的场景,而 modules: 'auto' 更适合需要直接运行或兼容旧环境的场景。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











