node.js运行时报错ReferenceError: require is not defined

一、背景与问题

在Node.js 12版本之前，CommonJS是默认的模块系统，开发者通过require加载模块。随着Node.js 14版本引入ES模块（ESM），默认模块系统发生了重大变化。当开发者在使用ESM时错误地使用require语句时，会遇到ReferenceError: require is not defined的错误。

这个错误的核心在于：ESM和CommonJS模块系统的运行机制存在本质差异。ESM通过import/export语句进行模块管理，而CommonJS依赖于全局的require函数。当开发者在ESM环境中使用require时，会触发此错误。

二、基本原理

1. 模块系统演变

Node.js的模块系统经历了以下演变过程：

CommonJS（Node.js 0.10 ~ 12.x）：

const fs = require('fs');
module.exports = { fs };

ESM（Node.js 12+）：

import fs from 'fs';
export default { fs };

2. 模块加载机制差异

特性	CommonJS	ESM
模块加载方式	`require()`	`import`/`import.meta`
模块导出方式	`module.exports`	`export`/`export default`
动态加载	支持	支持（需使用`import()`）
文件扩展名	自动识别	需要`.mjs`或`.cjs`扩展名
模块类型	默认为CommonJS	默认为ESM

3. 错误触发条件

当同时满足以下条件时会触发错误：

项目使用ESM（type: 'module'在package.json中）
使用require()加载模块
未正确配置模块类型

三、环境准备

1. 环境要求

Node.js 14.x 或更高版本
操作系统：Linux/macOS/Windows

项目结构：

my-project/
├── package.json
├── index.js
└── utils/
    └── helper.js

2. 初始化项目

mkdir my-project
cd my-project
npm init -y

3. 模块类型配置

在package.json中指定模块类型：

{
  "type": "module"
}

四、核心实现

1. 正确使用ESM的示例

// utils/helper.js
import { readFileSync } from 'fs';

export function readFile(filePath) {
  return readFileSync(filePath, 'utf-8');
}

// index.js
import { readFile } from './utils/helper.js';

const content = readFile('data.txt');
console.log(content);

2. 错误使用CommonJS的示例

// utils/helper.js
const fs = require('fs');
module.exports = {
  readFile: (filePath) => fs.readFileSync(filePath, 'utf-8')
};

// index.js
const { readFile } = require('./utils/helper.js');
// 此时会报错：ReferenceError: require is not defined

3. 混合使用场景的解决方案

当需要同时使用CommonJS和ESM时，可以通过以下方式处理：

// utils/helper.js
// 通过设置type字段强制使用CommonJS
// package.json中设置"type": "commonjs"

const fs = require('fs');
module.exports = {
  readFile: (filePath) => fs.readFileSync(filePath, 'utf-8')
};

// index.js
import { readFile } from './utils/helper.js';
// 需要使用TypeScript或Babel进行转换

五、完整案例

1. 项目结构

my-project/
├── package.json
├── index.js
├── utils/
│   └── helper.js
└── data.txt

2. 项目配置

{
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}

3. 代码实现

// utils/helper.js
import { readFileSync } from 'fs';

export function readFile(filePath) {
  return readFileSync(filePath, 'utf-8');
}

// index.js
import { readFile } from './utils/helper.js';

try {
  const content = readFile('data.txt');
  console.log('读取内容:', content);
} catch (err) {
  console.error('读取失败:', err.message);
}

4. 运行流程

安装依赖：npm install
运行项目：npm start
如果存在data.txt文件，会输出文件内容

六、源码解析

1. Node.js模块加载机制

在Node.js中，模块加载主要通过Module类实现：

// 内部实现简化版（伪代码）
class Module {
  constructor(id) {
    this.id = id;
    this.exports = {};
  }

  compile(code) {
    // 解析模块代码
    // 处理import/require语句
  }
}

2. ESM的特殊处理

当遇到.mjs文件时，Node.js会进行以下处理：

读取文件内容
使用acorn解析为AST
执行AST中的import语句
构建模块依赖图

3. 错误触发点

当在.mjs文件中使用require()时，会触发以下错误：

// 错误示例
const fs = require('fs'); // 此时会报错：ReferenceError: require is not defined

七、进阶使用

1. 动态导入（Dynamic Import）

async function loadModule() {
  const module = await import('./utils/helper.js');
  return module.readFile('data.txt');
}

2. 模块类型转换

使用Babel进行CommonJS到ESM的转换：

{
  "babel": {
    "presets": ["@babel/preset-env"]
  }
}

3. 使用TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2018",
    "moduleResolution": "node"
  }
}

八、性能与工程实践

1. 性能优化

预编译：使用node --experimental-modules进行预编译
缓存机制：Node.js自动缓存模块，但需注意缓存失效策略
代码分割：通过动态导入实现按需加载

2. 安全考量

动态导入风险：import()可能引入未验证的模块
模块注入：避免通过变量拼接导入模块
沙箱环境：使用vm模块创建隔离环境

3. 异常处理

try {
  await import('./nonexistent.js');
} catch (err) {
  console.error('模块加载失败:', err.message);
}

九、常见问题与踩坑

1. 常见错误场景

场景	错误信息	解决方案
混合使用CommonJS/ESM	ReferenceError: require is not defined	使用TypeScript或Babel进行转换
浏览器端使用Node模块	ReferenceError: require is not defined	使用Webpack打包后运行
动态导入未处理错误	Uncaught (in promise) ...	添加错误处理逻辑
模块类型配置错误	Module not found: ...	检查`package.json`中的`type`字段

2. 常见错误示例

// 错误示例
const fs = require('fs'); // 在.mjs文件中运行时会报错

// 正确示例
import fs from 'fs'; // 在.mjs文件中运行时正常

3. 常见性能陷阱

频繁动态导入导致内存泄漏
未使用缓存直接重复加载相同模块
未进行模块依赖分析导致冗余加载

十、最佳实践

1. 推荐方案

明确模块类型：在package.json中指定type字段
使用TypeScript：通过类型系统保证模块规范
统一模块规范：在团队中统一使用ESM或CommonJS
使用打包工具：通过Webpack/Vite进行模块打包
设置默认模块类型：在package.json中设置"type": "module"或"type": "commonjs"

2. 不推荐方案

混合使用模块系统：可能导致难以维护的代码结构
直接使用require：在ESM环境中会引发错误
硬编码模块路径：应使用相对路径或模块标识符
忽略错误处理：动态导入应始终包含错误处理逻辑

十一、总结

ReferenceError: require is not defined错误本质上是Node.js模块系统演进带来的技术挑战。理解CommonJS与ESM的核心差异，掌握正确的模块加载方式，是避免该错误的关键。在实际开发中，应根据项目需求选择合适的模块系统，同时注意版本兼容性问题。对于需要同时支持旧代码和新特性的项目，建议使用TypeScript或打包工具进行兼容处理。通过合理的设计和规范的模块管理，可以有效提升代码质量和项目可维护性。