Nuxt 原生 ES Modules 实战指南：从 Node.js 模块解析到 CJS 兼容排错与库迁移

Nuxt 原生 ES Modules 实战指南：从 Node.js 模块解析到 CJS 兼容排错与库迁移

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt

本文围绕 Nuxt 官方文档 ES Modules 概念指南 展开，系统讲解 CommonJS 与 ESM 的核心差异、Node.js 原生 ESM 的启用方式与模块解析规则，并结合 Nuxt 仓库源码（package.json的exports/imports字段、@nuxt/kit的interopDefault与importModule实现）说明 Nuxt 生态如何处理 ESM/CJS 兼容问题。读完后你将掌握三类实战能力：诊断SyntaxError: Unexpected token 'export'等模块解析错误的根因、通过build.transpile/alias在 Nuxt 配置中绕过有问题的依赖、以及按照官方建议把上游库从 CJS 迁移到标准 ESM 的完整改造路径。

背景：CJS、ESM 语法与"原生 ESM"

CommonJS 模块

CommonJS（CJS）是 Node.js 引入的模块格式，用于在相互隔离的 JavaScript 模块之间共享功能。其经典写法是：

const a = require('./a') module.exports.a = a

webpack、Rollup 这类打包器支持该语法，因此可以把以 CJS 编写的模块用在浏览器环境中。

ESM 语法

多数人讨论 ESM vs. CJS 时，指的核心其实是模块的书写语法不同：

import a from './a' export { a }

在 ECMAScript 模块成为语言标准之前（这个过程耗时超过 10 年），webpack 等工具甚至 TypeScript 就已经支持了所谓"ESM 语法"。但这种早期支持与最终规范存在一些关键差异，理解这一点是后文所有兼容性问题（命名导出缺失、默认导出嵌套）的根源。

什么是"原生" ESM？

浏览器原生支持 ESM 语法早已不是新闻；在 Nuxt 2 时代，框架会把服务端代码编译成 CJS、浏览器代码编译成 ESM，用户无感知。但引入第三方库时情况不同：当时的库通常会同时发布 CJS 与 ESM 两个版本，并在package.json中用两个字段分别声明：

{ "name": "sample-library", "main": "dist/sample-library.cjs.js", "module": "dist/sample-library.esm.js" }

在 Nuxt 2 中，打包器（webpack）为服务端构建拉取 CJS 文件（main字段），为客户端构建使用 ESM 文件（module字段）。需要注意：module字段只是 webpack、Rollup 等打包器遵循的约定，Node.js 本身并不认识它——Node.js 只用exports与main字段做模块解析。

而在较新的 Node.js LTS 版本中，可以直接在 Node.js 内运行原生 ESM。也就是说 Node.js 自己能处理 ESM 语法，只是默认不启用。启用 ESM 语法的两种最常见方式：

• 在package.json中设置"type": "module"，继续使用.js扩展名；
• 使用.mjs文件扩展名（官方推荐，更显式）。

Nuxt 的构建产物（Nitro 输出）就是这种做法：输出的.output/server/index.mjs文件通过.mjs扩展名告诉 Node.js"这是一个原生 ES 模块"。

Nuxt 仓库本身就是这些规则的实践样本。仓库根目录的 package.json 声明了"type": "module"，整个 monorepo 以原生 ESM 开发；packages/nuxt/package.json 同样声明"type": "module"，其 CLI 入口bin指向 nuxt.mjs。更进一步，Nuxt 包完整演示了现代 Node.js 包的声明方式：

{ "exports": { ".": { "types": "./types.dev.d.ts", "default": "./src/index.ts" }, "./config": { "types": "./config.d.ts", "import": "./config.js", "require": "./config.js" } }, "imports": { "#app": "./src/app/index.ts", "#app/nuxt": "./src/app/nuxt.ts" } }

• exports字段定义了包对外暴露的子路径（./config、./kit、./schema、./entry等），并区分types/import条件；
• 其中./config子路径同时提供import与require条件，保证 CJS 消费者也能require('nuxt/config')；
• imports字段（#app等）是包内部使用的子路径导入，避免写相对路径。

发布时的产物映射写在publishConfig.exports中：入口import条件指向./dist/index.mjs（原生 ESM 产物），而./config的require条件指向./config.cjs——即"ESM 用.mjs、CJS 用.cjs"的显式命名正是本文推荐的迁移方式。当前仓库中 config.js 与 kit.js 本身就是最简 ESM 转发层（export { defineNuxtConfig }/export * from '@nuxt/kit'）。

Node.js 上下文下哪些 import 是合法的？

当使用import而非require引入模块时，Node.js 的解析逻辑不同：导入sample-library时，Node.js 会查看该库package.json的exports条目；若未定义exports，则回退到main条目。动态导入（const b = await import('sample-library')）同理。

Node.js 支持的文件类型规则（按 Node.js 官方模块解析文档 转述）：

1. 以.mjs结尾的文件——期望使用 ESM 语法；
2. 以.cjs结尾的文件——期望使用 CJS 语法；
3. 以.js结尾的文件——期望使用 CJS 语法，除非其package.json声明了"type": "module"。

会出现哪些问题？

长期以来，库作者一直在产出"ESM 语法"的构建产物，但使用.esm.js、.es.js这类约定扩展名，并写入module字段。这在打包器主导的时代毫无问题——webpack 并不关心文件扩展名。但如果你尝试在Node.js ESM 上下文中导入这类包，就会失败，典型报错如下：

(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 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) ...

排查 ESM 问题：Nuxt 侧的三种处理手段

遇到上述错误，问题几乎必然在上游库本身——它们需要修改自身以支持被 Node.js 导入（见下文"库作者指南"）。在此之前，Nuxt 侧有三个可用的过渡手段。

手段一：将库加入build.transpile

告诉 Nuxt 不要直接把这些库当外部依赖导入，而是纳入打包/转译流程：

export default defineNuxtConfig({ build: { transpile: ['sample-library'], }, })

有时你还需要把这些库自身所导入的其他包一并加入。这一配置项在源码中是真实生效的链路：模块安装时会把模块根目录自动追加进该列表（见 packages/kit/src/module/install.ts 的nuxt.options.build.transpile.push(...)）；组件模块扫描到node_modules中的组件目录时也会自动转译（见 packages/nuxt/src/components/module.ts）；最终 Nitro 服务端构建会消费其中的字符串条目（见 packages/nitro-server/src/index.ts）。此外，Nuxt 的诊断信息也给出了同一建议——当某个自动导入在第三方库中失效时，提示"把该库加入build.transpile"（见 packages/nuxt/src/app/diagnostics/core.ts）。

手段二：手动别名到 CJS 版本

某些情况下需要手动把库别名指向其 CJS 产物：

export default defineNuxtConfig({ alias: { 'sample-library': 'sample-library/dist/sample-library.cjs.js', }, })

手段三：理解并处理默认导出（interop default）

一个 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 }

但由于语法探测的复杂性和不同打包格式的干扰，interop 默认值有时失效，会出现：

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)

对于更复杂、更求稳的场景，官方推荐使用mlly的interopDefault，它能保留命名导出：

import { interopDefault } from 'mlly' // 假设模块形态是 { default: { foo: 'bar' }, baz: 'qux' } import myModule from 'my-module' console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }

Nuxt 仓库内置了同一机制的实现：@nuxt/kit的 interop.ts 导出了interopDefault函数——它取模块命名空间的default导出，并将其余命名导出以 getter 的方式嫁接上去，从而让"CJS 转译产物"可像 ESM 一样被消费；而 esm.ts 中的importModule在动态import()之后默认就会调用interopDefault解包结果（可用interopDefault: false关闭）。这正好对应上文手动m.default || m的库内化版本。

与"原生 ESM"配合的另一面是回退机制：@nuxt/kit将 jiti.ts 中维护了一份"加载器错误码"清单（ERR_REQUIRE_ESM、ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX、ERR_MODULE_NOT_FOUND等），当原生import()因运行环境不支持而失败（如文件是 TypeScript、或在 ESM 上下文里遇到 CJS 语法）时，判定为"加载器拒绝"而非"文件自身抛错"，并回退到 jiti 转译加载；若项目中未声明jiti依赖，shouldReportJitiFallbackOnce 还会向用户报告一次回退行为。这解释了 Nuxt 配置链"能用原生 ESM 就直接import，不行才走转译"的实际工程策略。

库作者指南：让库支持被 Node.js 原生导入

修复 ESM 兼容性问题并不复杂，有两条主要路线：

1. 把 ESM 文件重命名为.mjs结尾（推荐，最简单）。可能需要顺带处理依赖与构建系统的问题，但多数情况下这一步就能解决。同理建议把 CJS 文件重命名为.cjs结尾，以获得最大的显式性。
2. 整个库改为 ESM-only。即在package.json设置"type": "module"，并确保构建产物全部使用 ESM 语法。代价是：你可能要处理依赖问题，且该库只能在 ESM 上下文中被消费。

迁移步骤

从 CJS 到 ESM 的第一步，是把require用法替换为import：

// Before module.exports = function () { /* ... */ } exports.hello = 'world'

// After export default function () { /* ... */ } export const hello = 'world'

// Before const myLib = require('my-lib')

// After import myLib from 'my-lib' // 或 const dynamicMyLib = await import('my-lib').then(lib => lib.default || lib)

在 ESM 模块中，require、require.resolve、__filename、__dirname这些 CJS 全局变量不再可用，需要改用import()与import.meta体系：

// Before const { join } = require('node:path') const newDir = join(__dirname, 'new-dir')

// After import { fileURLToPath } from 'node:url' const newDir = fileURLToPath(new URL('./new-dir', import.meta.url))

对于require.resolve的替代，Nuxt 生态自身的做法是 exsolve（Nuxt 的核心依赖之一）提供的resolveModulePath：

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

// After import { resolveModulePath } from 'exsolve' const someFile = resolveModulePath('my-lib', { from: import.meta.url })

@nuxt/kit内部正是用resolveModulePath（而非require.resolve）完成所有模块定位的，例如 esm.ts 的resolveModule与 exports.ts 中解析导出名时的路径解析，都以import.meta.url作为解析起点。

最佳实践

• 优先使用命名导出而非默认导出——这能减少与 CJS 的冲突（参见上文"默认导出"一节的 interop 问题）。
• 尽量避免依赖 Node.js 内建模块以及 CommonJS/仅 Node.js 可用的依赖，以便库能在浏览器和 Edge Workers 中直接运行，无需 Nitro polyfill。
• 使用新的exports字段配合条件导出：

{ "exports": { ".": { "import": "./dist/mymodule.mjs" } } }

小结：从 Nuxt 仓库看 ESM 工程化要点

把本文结论回收到 Nuxt 仓库的实证上，可以形成一张清晰的对照表：

对于应用开发者：遇到 ESM 相关报错时，先按"转译（build.transpile）→ 别名（alias指向 CJS 产物）→ 手动解包默认导出"的顺序在nuxt.config.ts中处理；对于库作者：最稳妥的路径是.mjs/.cjs显式命名 +"exports"条件导出 + 命名导出优先。Nuxt 官方文档的完整说明见 docs/3.guide/1.concepts/7.esm.md。

【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt