ES 模块
本指南帮助解释什么是 ES 模块以及如何使 Nuxt 应用(或上游库)与 ESM 兼容。
背景
CommonJS 模块
CommonJS(CJS)是 Node.js 引入的一种格式,允许在孤立的 JavaScript 模块之间共享功能(了解更多)。 你可能已经熟悉这种语法:
const a = require('./a')
module.exports.a = a
像 webpack 和 Rollup 这样的打包工具支持这种语法,并允许您在浏览器中使用编写的 CommonJS 模块。
ESM 语法
大多数时候,当人们谈论 ESM 与 CJS 时,他们是在谈论编写 模块 的不同语法。
import a from './a'
export { a }
在 ECMAScript 模块(ESM)成为标准之前(花了超过 10 年的时间!),像 webpack 这样的工具,甚至 TypeScript 这样的语言开始支持所谓的 ESM 语法。 然而,实际规范存在一些关键差异;这是 一个有帮助的解释。
什么是“原生” ESM?
您可能早已使用 ESM 语法编写应用程序。毕竟,浏览器原生支持它,在 Nuxt 2 中,我们将您编写的所有代码编译成适当的格式(服务器使用 CJS,浏览器使用 ESM)。
在将模块添加到您的包时,事情会稍有不同。一个示例库可能同时暴露 CJS 和 ESM 版本,并让我们选择想要的版本:
{
"name": "sample-library",
"main": "dist/sample-library.cjs.js",
"module": "dist/sample-library.esm.js"
}
因此,在 Nuxt 2 中,打包工具(webpack)会拉取 CJS 文件('main')用于服务器构建,并使用 ESM 文件('module')用于客户端构建。
然而,在最近的 Node.js LTS 版本中,现在可以在 Node.js 中 使用原生 ESM 模块。这意味着 Node.js 本身可以使用 ESM 语法处理 JavaScript,尽管默认情况下并不这样做。启用 ESM 语法的两种最常见方法是:
- 在
package.json
中设置"type": "module"
并继续使用.js
扩展名 - 使用
.mjs
文件扩展名(推荐)
这就是我们为 Nuxt Nitro 所做的;我们输出一个 .output/server/index.mjs
文件。这告诉 Node.js 将此文件视为原生 ES 模块。
在 Node.js 上下文中有效的导入是什么?
当您 import
一个模块而不是 require
它时,Node.js 以不同方式解决它。例如,当您导入 sample-library
时,Node.js 将查找不是 main
而是该库的 package.json
中的 exports
或 module
条目。
动态导入也是如此,例如 const b = await import('sample-library')
。
Node 支持以下几种导入类型(请参见 文档):
- 以
.mjs
结尾的文件 - 预期使用 ESM 语法 - 以
.cjs
结尾的文件 - 预期使用 CJS 语法 - 以
.js
结尾的文件 - 预期使用 CJS 语法,除非它们的package.json
中具有"type": "module"
可能出现什么样的问题?
长期以来,模块作者一直在生成 ESM 语法构建,但使用像 .esm.js
或 .es.js
这样的约定,并将它们添加到其 package.json
的 module
字段中。直到现在,这还不是问题,因为它们仅被像 webpack 这样的打包工具使用,这些工具对文件扩展名并不特别关心。
但是,如果您尝试在 Node.js ESM 上下文中导入带有 .esm.js
文件的包,它将无法正常工作,您将收到类似的错误:
(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/path/to/index.js:1
export default {}
^^^^^^
SyntaxError: Unexpected token 'export'
at wrapSafe (internal/modules/cjs/loader.js:1001:16)
at Module._compile (internal/modules/cjs/loader.js:1049:27)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
....
at async Object.loadESM (internal/process/esm_loader.js:68:5)
如果您从 Node.js 认为是 CJS 的 ESM 语法构建中有命名导入,您也可能会收到此错误:
file:///path/to/index.mjs:5
import { named } from 'sample-library'
^^^^^
SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:
import pkg from 'sample-library';
const { named } = pkg;
at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
at async Loader.import (internal/modules/esm/loader.js:177:24)
at async Object.loadESM (internal/process/esm_loader.js:68:5)
解决 ESM 问题
如果遇到这些错误,几乎可以肯定问题出在上游库。它们需要 修复它们的库 以支持被 Node 导入。
转译库
在此期间,您可以告诉 Nuxt 不要尝试导入这些库,将它们添加到 build.transpile
中:
export default defineNuxtConfig({
build: {
transpile: ['sample-library']
}
})
您可能还会发现需要添加其他被这些库导入的包。
别名库
在某些情况下,您可能还需要手动将库别名为 CJS 版本,例如:
export default defineNuxtConfig({
alias: {
'sample-library': 'sample-library/dist/sample-library.cjs.js'
}
})
默认导出
具有 CommonJS 格式的依赖项可以使用 module.exports
或 exports
提供默认导出:
module.exports = { test: 123 }
// 或
exports.test = 123
如果我们 require
这样的依赖项,这通常工作良好:
const pkg = require('cjs-pkg')
console.log(pkg) // { test: 123 }
Node.js 在原生 ESM 模式下、启用了 esModuleInterop
的 TypeScript 和像 webpack 这样的打包工具提供了一种兼容机制,以便我们能够默认导入这样的库。
这种机制通常称为 "interop require default":
import pkg from 'cjs-pkg'
console.log(pkg) // { test: 123 }
然而,由于语法检测和不同打包格式的复杂性,始终有可能导致默认互操作失败,最终得到如下内容:
import pkg from 'cjs-pkg'
console.log(pkg) // { default: { test: 123 } }
此外,在使用动态导入语法时(在 CJS 和 ESM 文件中),我们总是有这样的情况:
import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { test: '123' } }
在这种情况下,我们需要手动互操作默认导出:
// 静态导入
import { default as pkg } from 'cjs-pkg'
// 动态导入
import('cjs-pkg').then(m => m.default || m).then(console.log)
为处理更复杂的情况和更安全,我们推荐并在 Nuxt 中内部使用 mlly,以便能保留命名导出。
import { interopDefault } from 'mlly'
// 假设格式为 { default: { foo: 'bar' }, baz: 'qux' }
import myModule from 'my-module'
console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }
库作者指南
好消息是,修复 ESM 兼容性问题相对简单。主要有两个选项:
- 您可以将 ESM 文件重命名为以
.mjs
结尾。
这是推荐的和最简单的方法。 您可能需要解决库的依赖项,也可能需要与构建系统一起解决问题,但在大多数情况下,这应该能为您解决问题。还建议将 CJS 文件重命名为以.cjs
结尾,以获得最大的明确性。 - 您可以选择使整个库仅为 ESM。
这意味着在package.json
中设置"type": "module"
并确保构建的库使用 ESM 语法。但是,您可能会面临依赖项问题——而这种方法意味着您的库 只能 在 ESM 上下文中被使用。
迁移
从 CJS 到 ESM 的第一步是将任何使用 require
的地方更新为使用 import
:
module.exports = ...
exports.hello = ...
export default ...
export const hello = ...
const myLib = require('my-lib')
import myLib from 'my-lib'
// 或
const myLib = await import('my-lib').then(lib => lib.default || lib)
在 ESM 模块中,与 CJS 不同的是,require
、require.resolve
、__filename
和 __dirname
全局变量不可用,并应替换为 import()
和 import.meta.filename
。
import { join } from 'path'
const newDir = join(__dirname, 'new-dir')
import { fileURLToPath } from 'node:url'
const newDir = fileURLToPath(new URL('./new-dir', import.meta.url))
const someFile = require.resolve('./lib/foo.js')
import { resolvePath } from 'mlly'
const someFile = await resolvePath('my-lib', { url: import.meta.url })
最佳实践
- 优先使用命名导出,而不是默认导出。这有助于减少 CJS 冲突。(请参见 默认导出 部分)
- 尽可能避免依赖 Node.js 内置模块以及 CommonJS 或仅限 Node.js 的依赖,以使您的库可以在浏览器和边缘工作者中使用,而无需使用 Nitro polyfills。
- 使用新的
exports
字段并包含条件导出。 (了解更多)。
{
"exports": {
".": {
"import": "./dist/mymodule.mjs"
}
}
}