Cannot find module 报错怎么解决？Node.js 模块找不到的 6 种原因与修复

现象：Cannot find module 'xxx'

Error: Cannot find module 'express'
Require stack:
- /app/server.js

或 ESM 形态：

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'lodash' imported from /app/index.js

两句话诊断完毕：Node 找不到你要求加载的那个模块文件。可能文件不存在、路径不对、或者没安装。

六种原因，按概率排序

1. 没安装（新手最常见）

npm install express    # 装了就好

判断方法：ls node_modules/express 是否存在。

2. 路径写错（相对路径忘了 ./）

require('utils');       // ❌ Node 去 node_modules 找 utils 包
require('./utils');     // ✅ 相对路径必须以 ./ 或 ../ 开头

区别一句话：不以 ./ ../ / 开头的路径一律去 node_modules 里找。

3. node_modules 损坏（安装中断/磁盘满）

rm -rf node_modules package-lock.json
npm install

删除重装能解决大部分诡异问题——node_modules 本质是临时产物，重装无损。

4. 大小写不匹配（macOS 能跑、Linux 炸）

macOS 文件系统默认大小写不敏感，require('./Utils') 能找到 utils.js；但 Linux（包括 Docker 容器和 CI 服务器）大小写敏感——本地能跑部署就炸的经典原因。

# 检查文件名实际大小写
ls -la src/utils/ | grep -i util

5. ESM 和 CommonJS 混用

package.json 里加了 "type": "module" 后，.js 文件全部按 ESM 解析：

| 写法 | CommonJS (.js) | ESM ("type":"module") | |---|---|---| | require('./x') | ✅ | ❌ ERR_MODULE_NOT_FOUND | | import x from './x.js' | ❌ | ✅（必须带扩展名） |

ESM 的两个关键差异：import 路径必须含文件扩展名（./utils.js 而非 ./utils），且不能省略 .js 后缀。

6. monorepo / workspace 路径问题

在 monorepo 中引用兄弟包时，确认 package.json 的 workspaces 配置包含了该包，且包名与 name 字段一致。

为什么删了 node_modules 重装能解决 80% 的问题

node_modules 的完整性依赖 npm install 一次成功执行到底。安装中途断网、Ctrl+C、磁盘满都可能留下半安装状态——文件夹存在但 package.json（包内的，描述依赖关系）缺失。重装重建整个目录树，比精确修复省时。

预防

1. CI 加 npm ci 而非 npm install——ci 严格按 lock 文件安装，不一致直接报错而非静默修复；
2. TypeScript 项目加 skipLibCheck 之前先跑一次类型检查——排除第三方类型报错的干扰；
3. monorepo 用 workspace 协议（"deps": {"@repo/utils": "workspace:*"}）代替相对路径。

排查清单

1. ls node_modules/<包名> — 目录存在？
2. 检查路径是否以 ./ 开头（相对路径）
3. rm -rf node_modules && npm install — 重装修复
4. 大小写核对（本地→部署炸 = 大概率这个）
5. "type": "module" 检查 — require vs import 是否匹配

本文由 ToolVault 工具匣 提供。相关工具：Linux 命令速查。相关阅读：npm 换源指南、Node 17+ 报 digital envelope routines 错误排查、npm ERESOLVE 依赖冲突。访问 首页 查看更多开发者工具。