v3.17
GitHub

ES 模块

Nuxt 使用原生 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 支持以下几种导入类型（请参见 文档）：

  1. 以 .mjs 结尾的文件 - 预期使用 ESM 语法
  2. 以 .cjs 结尾的文件 - 预期使用 CJS 语法
  3. 以 .js 结尾的文件 - 预期使用 CJS 语法，除非它们的 package.json 中具有 "type": "module"

可能出现什么样的问题？

长期以来，模块作者一直在生成 ESM 语法构建，但使用像 .esm.js 或 .es.js 这样的约定，并将它们添加到其 package.json 的 module 字段中。直到现在，这还不是问题，因为它们仅被像 webpack 这样的打包工具使用，这些工具对文件扩展名并不特别关心。

但是，如果您尝试在 Node.js ESM 上下文中导入带有 .esm.js 文件的包，它将无法正常工作，您将收到类似的错误：

Terminal
(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 语法构建中有命名导入，您也可能会收到此错误：

Terminal
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 提供默认导出：

node_modules/cjs-pkg/index.js
module.exports = { test: 123 }
// 或
exports.test = 123

如果我们 require 这样的依赖项，这通常工作良好：

test.cjs
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 兼容性问题相对简单。主要有两个选项：

  1. 您可以将 ESM 文件重命名为以 .mjs 结尾。
    这是推荐的和最简单的方法。 您可能需要解决库的依赖项，也可能需要与构建系统一起解决问题，但在大多数情况下，这应该能为您解决问题。还建议将 CJS 文件重命名为以 .cjs 结尾，以获得最大的明确性。
  2. 您可以选择使整个库仅为 ESM。
    这意味着在 package.json 中设置 "type": "module" 并确保构建的库使用 ESM 语法。但是，您可能会面临依赖项问题——而这种方法意味着您的库 只能 在 ESM 上下文中被使用。

迁移

从 CJS 到 ESM 的第一步是将任何使用 require 的地方更新为使用 import：

module.exports = ...

exports.hello = ...

const myLib = require('my-lib')

在 ESM 模块中，与 CJS 不同的是，require、require.resolve、__filename 和 __dirname 全局变量不可用，并应替换为 import() 和 import.meta.filename。

import { join } from 'path'

const newDir = join(__dirname, 'new-dir')

const someFile = require.resolve('./lib/foo.js')

最佳实践

  • 优先使用命名导出，而不是默认导出。这有助于减少 CJS 冲突。（请参见 默认导出 部分）
  • 尽可能避免依赖 Node.js 内置模块以及 CommonJS 或仅限 Node.js 的依赖，以使您的库可以在浏览器和边缘工作者中使用，而无需使用 Nitro polyfills。
  • 使用新的 exports 字段并包含条件导出。 （了解更多）。
{
  "exports": {
    ".": {
      "import": "./dist/mymodule.mjs"
    }
  }
}