从ERR_REQUIRE_ESM错误看现代JavaScript模块化：ESLint配置中的CommonJS与ES Module混用指南
从ERR_REQUIRE_ESM错误看现代JavaScript模块化：ESLint配置中的CommonJS与ES Module混用指南
如果你是一位中高级前端开发者，最近在配置ESLint时遇到ERR_REQUIRE_ESM错误，那么这篇文章正是为你准备的。这个看似简单的错误背后，实际上反映了JavaScript模块化发展历程中的重大变革。随着ES Module（ESM）逐渐成为主流，我们不得不面对CommonJS（CJS）与ESM混用带来的各种兼容性问题。本文将带你深入理解模块化的工作原理，分析错误根源，并提供在ESLint配置中处理模块混用的最佳实践方案。
1. JavaScript模块化发展简史
要理解ERR_REQUIRE_ESM错误的本质，我们需要先回顾JavaScript模块化的发展历程。JavaScript最初并没有内置的模块系统，这导致了各种社区解决方案的出现。
1.1 CommonJS的兴起与Node.js
CommonJS模块系统最初是为服务器端JavaScript设计的，后来被Node.js采用并广泛使用。它的特点是：
- 使用
require()函数同步加载模块 - 使用
module.exports或exports导出模块 - 模块加载是运行时行为
// CommonJS模块示例 const fs = require('fs'); module.exports = function() { // 模块内容 };1.2 ES Module的标准化
ES6（ES2015）引入了官方的模块系统——ES Module，其特点是：
- 使用
import和export语法 - 静态分析，支持tree-shaking
- 异步加载能力
- 严格模式默认启用
// ES Module示例 import fs from 'fs'; export default function() { // 模块内容 }1.3 两种模块系统的关键差异
| 特性 | CommonJS | ES Module |
|---|---|---|
| 加载方式 | 同步 | 异步 |
| 解析时机 | 运行时 | 编译时 |
| 导出类型 | 动态引用 | 静态绑定 |
| 循环依赖处理 | 支持但不完美 | 设计上支持 |
| 严格模式 | 默认不启用 | 默认启用 |
| 顶层this | 指向模块本身 | undefined |
2. ERR_REQUIRE_ESM错误深度解析
当你在项目中看到Error [ERR_REQUIRE_ESM]: require() of ES Module这样的错误时，这意味着你正尝试用CommonJS的require()函数加载一个ES Module模块。
2.1 错误产生的根本原因
这个错误的产生源于Node.js对两种模块系统的处理方式：
- 模块识别：Node.js通过文件扩展名（.js, .mjs, .cjs）或package.json中的
type字段来判断模块类型 - 加载机制：CommonJS的
require()不能直接加载ES Module，因为两者的加载机制和解析方式完全不同
2.2 典型错误场景分析
在实际开发中，以下几种情况容易引发此错误：
- 依赖库更新：某个依赖库从CommonJS迁移到了ES Module，但你的项目仍在使用
require() - 配置文件格式：像ESLint、Babel等工具的配置文件使用了错误的模块格式
- 混合开发环境：项目中同时存在CommonJS和ES Module文件，且相互引用
2.3 错误堆栈解读
以原始文章中的错误为例：
Error [ERR_REQUIRE_ESM]: require() of ES Module C:\Users\USER\Desktop\tindin\node_modules\node-fetch\src\index.js from C:\Users\USER\Desktop\tindin\src\api\services\unsplash.ts not supported.这段错误信息告诉我们：
- 问题发生在
unsplash.ts文件中 - 它尝试用
require()加载node-fetch模块 - 但
node-fetch已经是一个ES Module
3. ESLint配置中的模块混用问题
ESLint作为前端工程化的重要工具，其配置文件的模块格式选择尤为关键。下面我们重点探讨ESLint环境下的解决方案。
3.1 ESLint配置文件的模块格式
ESLint支持多种配置文件格式：
.eslintrc.js- 通常使用CommonJS.eslintrc.cjs- 明确使用CommonJS.eslintrc.mjs- 明确使用ES Module.eslintrc.json- JSON格式，无模块系统问题
3.2 常见问题解决方案
方案一：更改文件扩展名
如原始文章中提到的解决方案，将配置文件改为.cjs扩展名：
# 将 commitlint.config.js # 改为 commitlint.config.cjs这种方法明确告诉Node.js这是一个CommonJS模块，避免与项目中的ES Module配置冲突。
方案二：调整package.json配置
在项目的package.json中明确指定模块类型：
{ "type": "commonjs", "scripts": { // ... } }或者为特定文件指定类型：
{ "type": "module", "scripts": { // ... }, "eslintConfig": { // ESLint配置 } }方案三：使用动态导入
对于必须使用require()加载ES Module的情况，可以使用动态import()：
// 替换 const fetch = require('node-fetch'); // 使用 const fetch = await import('node-fetch').then(m => m.default);注意：动态
import()返回的是一个Promise，需要在async函数中使用。
3.3 ESLint配置最佳实践
基于不同项目类型，推荐以下配置方式：
纯CommonJS项目：
- 使用
.eslintrc.js或.eslintrc.cjs - package.json中不设置或设置
"type": "commonjs"
- 使用
纯ES Module项目：
- 使用
.eslintrc.mjs - package.json中设置
"type": "module"
- 使用
混合模块项目：
- 为配置文件使用明确的扩展名（.cjs或.mjs）
- 使用
overrides配置不同模块类型的规则
// .eslintrc.cjs示例 module.exports = { env: { node: true, es2021: true }, extends: 'eslint:recommended', parserOptions: { ecmaVersion: 'latest', sourceType: 'module' // 即使使用CommonJS配置文件，也可以检查ES Module代码 }, rules: { // 规则配置 } };4. 现代JavaScript项目模块化实践
随着ES Module成为JavaScript标准，我们需要逐步将项目迁移到ES Module体系。以下是迁移过程中的关键考虑因素。
4.1 渐进式迁移策略
评估依赖关系：
- 使用
npm ls检查项目依赖树 - 识别关键依赖的模块类型
- 使用
配置文件先行：
- 先将构建工具(ESLint、Babel等)配置文件迁移
- 使用明确的文件扩展名(.cjs/.mjs)
代码分步迁移：
- 从项目边缘模块开始
- 逐步向核心代码推进
测试保障：
- 每次迁移后运行完整测试
- 特别注意模块边界处的测试
4.2 工具链配置建议
现代前端工具链对ES Module的支持情况：
| 工具 | ESM支持情况 | 备注 |
|---|---|---|
| Node.js | ≥12.0.0 (实验性)，≥14.13.0 (稳定) | 需要package.json中"type":"module" |
| ESLint | 支持 | 配置文件需使用.mjs扩展名 |
| Babel | 完全支持 | 可以转换ESM到CJS |
| Webpack | 支持 | 需要适当配置 |
| TypeScript | 支持 | 需设置"module": "ESNext" |
4.3 常见兼容性处理技巧
- __dirname替代方案：
// CommonJS中的__dirname在ESM中需要这样实现 import { fileURLToPath } from 'url'; import { dirname } from 'path'; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename);- JSON文件导入：
// CommonJS const pkg = require('./package.json'); // ESM import { createRequire } from 'module'; const require = createRequire(import.meta.url); const pkg = require('./package.json');- 条件加载模块：
async function loadModule() { let myModule; try { // 尝试ESM方式加载 myModule = await import('some-module'); } catch (e) { // 回退到CommonJS myModule = require('some-module'); } return myModule; }5. 未来展望与升级建议
JavaScript生态系统正在全面转向ES Module，作为开发者我们需要：
- 拥抱ES Module：新项目优先使用ES Module
- 了解互操作：掌握两种模块系统互操作的技巧
- 关注工具更新：保持工具链的最新版本以获得最佳支持
- 逐步迁移：对现有项目制定合理的迁移计划
在实际项目中处理ERR_REQUIRE_ESM错误时，最关键的是理解错误的根源——模块系统的不匹配。通过明确配置文件格式、合理使用文件扩展名、必要时使用动态导入，可以有效地解决这类问题。