介绍

¥Introduction

当传递给 node 作为初始输入时，或者当被 import 语句或 import() 表达式引用时，Node.js 会将以下内容视为 ES 模块：

¥Node.js will treat the following as ES modules when passed to node as the initial input, or when referenced by import statements or import() expressions:

  • 扩展名为 .mjs 的文件。

    ¥Files with an .mjs extension.

  • 当最近的父 package.json 文件包含值为 "module" 的顶层 "type" 字段时，扩展名为 .js 的文件。

    ¥Files with a .js extension when the nearest parent package.json file contains a top-level "type" field with a value of "module".

  • 字符串作为参数传入 --eval，或通过 STDIN 管道传输到 node，带有标志 --input-type=module。

    ¥Strings passed in as an argument to --eval, or piped to node via STDIN, with the flag --input-type=module.

  • 代码包含仅成功解析为 ES 模块 的语法，例如 import 或 export 语句或 import.meta，没有明确标记应如何解释。显式标记是 .mjs 或 .cjs 扩展、具有 "module" 或 "commonjs" 值的 package.json "type" 字段或 --input-type 标志。CommonJS 或 ES 模块均支持动态 import() 表达式，并且不会强制将文件视为 ES 模块。参见 语法检测。

    ¥Code containing syntax only successfully parsed as ES modules, such as import or export statements or import.meta, with no explicit marker of how it should be interpreted. Explicit markers are .mjs or .cjs extensions, package.json "type" fields with either "module" or "commonjs" values, or the --input-type flag. Dynamic import() expressions are supported in either CommonJS or ES modules and would not force a file to be treated as an ES module. See Syntax detection.

当传递给 node 作为初始输入时，或者当被 import 语句或 import() 表达式引用时，Node.js 会将以下内容视为 CommonJS：

¥Node.js will treat the following as CommonJS when passed to node as the initial input, or when referenced by import statements or import() expressions:

  • 扩展名为 .cjs 的文件。

    ¥Files with a .cjs extension.

  • 当最近的父 package.json 文件包含值为 "commonjs" 的顶层字段 "type" 时，则扩展名为 .js 的文件。

    ¥Files with a .js extension when the nearest parent package.json file contains a top-level field "type" with a value of "commonjs".

  • 字符串作为参数传入 --eval 或 --print，或通过 STDIN 管道传输到 node，带有标志 --input-type=commonjs。

    ¥Strings passed in as an argument to --eval or --print, or piped to node via STDIN, with the flag --input-type=commonjs.

  • 具有 .js 扩展名但没有父 package.json 文件的文件，或者最近的父 package.json 文件缺少 type 字段，并且代码可以成功评估为 CommonJS。换句话说，Node.js 首先尝试将此类 "ambiguous" 文件作为 CommonJS 运行，如果由于解析器发现 ES 模块语法而导致评估为 CommonJS 失败，则会重试将它们评估为 ES 模块。

    ¥Files with a .js extension with no parent package.json file or where the nearest parent package.json file lacks a type field, and where the code can evaluate successfully as CommonJS. In other words, Node.js tries to run such "ambiguous" files as CommonJS first, and will retry evaluating them as ES modules if the evaluation as CommonJS fails because the parser found ES module syntax.

在 "ambiguous" 文件中编写 ES 模块语法会产生性能成本，因此鼓励作者尽可能明确说明。特别是，包作者应始终在其 package.json 文件中包含 "type" 字段，即使在所有源都是 CommonJS 的包中也是如此。如果 Node.js 的默认类型发生变化，显式说明包的 type 将使包面向未来，它还将使构建工具和加载器更容易确定应如何解释包中的文件。

¥Writing ES module syntax in "ambiguous" files incurs a performance cost, and therefore it is encouraged that authors be explicit wherever possible. In particular, package authors should always include the "type" field in their package.json files, even in packages where all sources are CommonJS. Being explicit about the type of the package will future-proof the package in case the default type of Node.js ever changes, and it will also make things easier for build tools and loaders to determine how the files in the package should be interpreted.