Node.js 中 ES 模块加载错误的解决方案

问题描述

当在 Node.js 环境中使用 ES 模块语法（import/export）时，可能会遇到以下警告信息：

(node:9374) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.

这个错误通常发生在使用现代 JavaScript 模块语法（如 import React from "react"）时，而 Node.js 默认使用的是 CommonJS 模块系统。

解决方案

方法一：在 package.json 中设置模块类型（推荐）

在项目的 package.json 文件中添加 "type": "module" 字段：

{
  "name": "your-project",
  "version": "1.0.0",
  "type": "module",
  // 其他配置...
}

注意事项

• 此设置会使项目中的所有 .js 文件被视为 ES 模块
• 设置后，不能再使用 require() 语法，必须使用 import/export
• 需要明确指定文件扩展名（如 import App from './App.js'）

兼容性问题

如果项目中有依赖使用 CommonJS 语法，可能会遇到兼容性问题。这种情况下可以考虑使用构建工具（如 Webpack）或选择其他解决方案。

方法二：使用 .mjs 扩展名

将使用 ES 模块语法的文件扩展名从 .js 改为 .mjs：

# 重命名文件
mv App.js App.mjs

# 导入时需要指定完整文件名
import App from './App.mjs';

INFO

这种方法适用于只想在特定文件中使用 ES 模块，而不影响项目其他部分的情况。

方法三：完整指定导入路径

确保导入语句中包含完整的文件扩展名：

// 错误写法
import App from './App';

// 正确写法
import App from './App.js';

方法四：TypeScript 配置调整

如果使用 TypeScript，确保 tsconfig.json 中的模块配置正确：

{
  "compilerOptions": {
    "module": "commonjs"
    // 其他配置...
  }
}

方法五：检查代码语法错误

有时警告信息可能掩盖了实际的语法错误。例如，在 React 组件中不正确的 JSX 语法：

// 错误写法
function App() {
  <>
  return (
    <h1>ToDo</h1>
  );
  </>
}

// 正确写法
function App() {
  return (
    <>
      <h1>ToDo</h1>
    </>
  );
}

解决方案对比

package.json 配置

{
  "type": "module",
  "main": "index.js"
}

.mjs 扩展名

// 文件名: module.mjs
export const example = 'Hello World';

// 导入
import { example } from './module.mjs';

完整扩展名

import React from 'react';
import App from './App.js';
import './App.css';

最佳实践建议

1. 新项目：推荐使用 "type": "module" 配置，这是现代 JavaScript 的发展方向
2. 现有项目：根据项目结构选择合适的方法，避免破坏现有代码
3. 混合模块：如果需要同时使用 ES 模块和 CommonJS，考虑使用构建工具处理模块转换
4. Node.js 版本：确保使用较新的 Node.js 版本（v12+），它们对 ES 模块的支持更加完善

总结

Node.js 中 ES 模块加载错误的主要解决方案包括在 package.json 中设置 "type": "module"、使用 .mjs 扩展名或确保导入路径完整。选择哪种方法取决于项目需求和技术栈。对于现代前端项目（如 React），推荐使用 "type": "module" 配置，这是最符合未来发展趋势的解决方案。