ERR_MODULE_NOT_FOUND 错误：找不到模块的解决方案

问题描述

在使用 Node.js ES 模块时，开发者经常遇到以下错误：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/module'

这个错误通常发生在尝试导入本地 JavaScript 文件时，特别是在从 CommonJS 迁移到 ES 模块的过程中。

问题根源

Node.js 的 ES 模块系统与 CommonJS 有几个关键区别：

1. 文件扩展名必需：ES 模块要求明确指定文件扩展名（.js、.mjs 等）
2. 目录索引文件解析：需要额外配置才能自动解析 index.js 文件
3. 模块解析算法：与 CommonJS 的 require() 解析方式不同

解决方案

方案一：添加文件扩展名（推荐）

在导入语句中明确指定 .js 扩展名：

// 错误写法
import { urls } from './helpers';

// 正确写法
import { urls } from './helpers.js';

这是最直接且符合规范的解决方案，适用于所有支持 ES 模块的 Node.js 版本。

方案二：配置 package.json

确保 package.json 中设置了 "type": "module"：

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

方案三：使用实验性标志（不推荐用于生产）

对于早期 Node.js 版本（v12-14），可以使用实验性标志：

node --experimental-specifier-resolution=node index.js

或者在 package.json 中配置：

{
  "scripts": {
    "start": "NODE_OPTIONS='--experimental-specifier-resolution=node' node index.js"
  }
}

WARNING

这是一个实验性功能，可能在未来的 Node.js 版本中被移除，不建议在生产环境中使用。

方案四：使用子路径导入（高级配置）

在 package.json 中配置路径映射：

{
  "imports": {
    "#helpers": "./helpers.js"
  }
}

然后在代码中使用：

import { urls } from '#helpers';

方案五：清理和重新安装依赖

有时候模块找不到的问题可能与依赖关系有关：

# 删除 node_modules 并重新安装
rm -rf node_modules
npm install

# 或者使用强制安装
npm install --legacy-peer-deps -f

TypeScript 配置

如果使用 TypeScript，确保 tsconfig.json 正确配置：

{
  "compilerOptions": {
    "lib": ["es2020"],
    "module": "ES2022",
    "moduleResolution": "node",
    "target": "es2022"
  }
}

常见错误模式

1. 遗漏相对路径前缀：

   // 错误
   import { urls } from 'helpers';
   
   // 正确
   import { urls } from './helpers.js';

2. 错误使用模块导出：

   // helpers.js - CommonJS 导出（不适用于 ES 模块）
   module.exports = { urls };
   
   // helpers.js - ES 模块导出
   export { urls };

最佳实践

1. 统一使用文件扩展名：始终在导入时包含 .js 扩展名
2. 明确模块类型：在 package.json 中明确设置 "type": "module"
3. 使用现代语法：优先使用 ES 模块的 import/export 语法
4. 保持依赖更新：定期更新 Node.js 版本以获得更好的 ES 模块支持

总结

ERR_MODULE_NOT_FOUND 错误通常是由于 ES 模块的严格解析规则导致的。通过添加文件扩展名、正确配置项目设置和使用合适的导入语法，可以轻松解决这个问题。随着 Node.js 对 ES 模块支持的不断完善，遵循这些最佳实践将确保代码的兼容性和可维护性。

INFO

Node.js 从版本 12 开始提供稳定的 ES 模块支持，建议使用 Node.js 16 或更高版本以获得最佳体验。