(node:17020) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token 'export'

Question

**问题描述：** 在运行 Node.js 应用时，控制台报错：`(node:17020) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token 'export'`。该错误通常发生在尝试使用 `export` 语法（如 `export default` 或 `export const`）时，但当前环境不支持 ES Modules 或文件未被正确识别为模块。常见于 Node.js 版本低于 14.0、未设置 `"type": "module"`，或在 CommonJS 模式下错误使用 ES6 的 `export` 语法。如何正确配置项目以支持 `export` 语法并解决该错误？

Answer 1

一、问题背景与错误现象

在 Node.js 应用开发中，开发者可能会遇到如下错误：

(node:17020) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token 'export'

该错误通常出现在尝试使用 ES6 的模块语法（如 export default 或 export const）时，但 Node.js 环境未能正确识别该文件为模块。这可能是由于 Node.js 版本不支持、项目配置缺失，或误将 ES Module 语法用于 CommonJS 模式所致。

二、常见原因分析

以下是导致该错误的几个主要原因：

1. Node.js 版本过低：Node.js 在 v12 及更早版本中默认不支持 ES Modules。
2. 未声明模块类型：即使 Node.js 支持模块系统，也需要在 package.json 中设置 "type": "module"。
3. 文件扩展名问题：未使用 .mjs 扩展名而试图使用 ES Module 语法。
4. 混合使用 CommonJS 和 ES Module 语法：在同一个项目中混合使用 require() 和 import/export 会导致解析错误。

三、解决方案与配置步骤

1. 检查 Node.js 版本

首先确认当前 Node.js 版本是否支持 ES Modules：

node -v

建议使用 Node.js v14 或更高版本。如版本较低，可通过 Node.js 官网 或使用 nvm 工具升级。

2. 配置 package.json 中的模块类型

在项目根目录的 package.json 文件中添加或修改如下字段：

{
  "type": "module"
}

该配置告诉 Node.js 将所有 .js 文件视为 ES Modules。

3. 使用 .mjs 扩展名（可选）

如果不想修改 package.json，可以将使用 export 和 import 的文件保存为 .mjs 格式，例如：

// utils.mjs
export const greet = () => {
  console.log('Hello from ES Module!');
};

4. 避免 CommonJS 与 ES Module 混用

ES Modules 与 CommonJS 是两种不同的模块系统。以下写法会导致错误：

import express from 'express'; // 正确
const http = require('http');   // 错误（在 ES Module 中）

应统一使用 import / export 或改用 .cjs 文件并配置 "type": "module" 为 "type": "commonjs"。

四、错误复现与调试流程

graph TD A[开始] --> B{Node.js 版本 >= 14?} B -- 是 --> C{"type": "module" 是否设置?} C -- 是 --> D[使用 import/export 正常] C -- 否 --> E[报错: Unexpected token 'export'] B -- 否 --> F[升级 Node.js] F --> G[重新设置模块类型] G --> H[重新运行]

五、最佳实践与建议

为避免此类问题，建议遵循以下最佳实践：

建议	说明
统一模块系统	选择使用 CommonJS 或 ES Modules，并在整个项目中保持一致。
设置 package.json type	明确声明模块类型，避免 Node.js 默认行为带来的问题。
使用现代 Node.js 版本	确保使用支持 ES Modules 的 Node.js 版本（v14+）。
使用 .mjs 或 .cjs 明确模块类型	通过文件扩展名显式区分模块类型，避免配置依赖。