ESM

ESM 是 JavaScript 标准模块系统。Node.js 通过 .mjs、.cjs 扩展名或最近的 package.json 的 type 字段确定模块类型。

json

{
  "type": "module"
}

js

// math.js
export function add(a, b) {
  return a + b
}

// app.js
import { add } from './math.js'
import { readFile } from 'node:fs/promises'

必知规则

相对和绝对 import 必须写完整扩展名：./math.js，不能写 ./math。
内置模块使用 node:，明确避免与三方包同名：node:path。
ESM 没有 require、module.exports、__filename 和 __dirname。
ESM 支持顶层 await，但入口模块的顶层等待会延迟整个模块图的执行。

当前文件与资源

Node.js 20.11+ 可使用 import.meta.dirname 和 import.meta.filename。为兼容较低版本，或加载相邻资源时，直接基于 import.meta.url 构造 URL：

js

import { readFile } from 'node:fs/promises'

const content = await readFile(new URL('./template.html', import.meta.url), 'utf8')

`exports` 边界

发布包时使用 package.json 的 exports 声明公共入口，避免消费者深层导入内部文件；条件导出可为 import 与 require 分别提供 ESM/CJS 入口。