一、问题/场景描述
在运行Node.js项目时，开发者经常会遇到“Error: Cannot find module ‘xxx’”的错误提示。该错误通常出现在启动应用、执行脚本或运行测试时，控制台会明确指示找不到某个特定的模块，导致程序无法正常启动或运行，是Node.js开发中的常见障碍。
二、原因分析
产生“cannot find module”错误的核心原因是Node.js的模块系统无法在预设的路径中找到请求的模块。具体可能由以下几种情况导致：首先，最常见的是未安装依赖，即package.json中声明的模块没有通过npm或yarn安装。其次，模块虽然已安装，但可能因为node_modules目录损坏、位置不正确或存在缓存问题而无法被正确解析。此外，引用模块时使用了错误的相对路径或模块名称拼写错误，也会直接触发此错误。理解这些原因是解决问题的第一步。
三、详细解决步骤
请按照以下步骤系统性地排查和解决问题。
步骤1：确认并安装缺失的依赖
首先，检查项目根目录下是否存在package.json文件，并确认报错中提到的模块是否在dependencies或devDependencies列表中。如果未安装，则需要安装。
# 进入项目根目录
cd /your/project/path
# 安装所有package.json中列出的依赖
npm install
# 或者，如果使用yarn
yarn install
如果只是缺少某个特定模块，可以单独安装。
npm install module-name
步骤2：检查模块引用路径
确保在代码中引用模块的路径是正确的。对于本地文件模块，使用相对路径时要以./或../开头。
// 错误示例：直接写目录名，Node会将其视为核心模块或node_modules中的模块
const myModule = require('utils/myModule');
// 正确示例：使用相对路径
const myModule = require('./utils/myModule');
同时，仔细检查模块名的大小写，因为某些操作系统是大小写敏感的。
步骤3：清理缓存并重新安装
有时npm的缓存或本地的node_modules目录可能存在问题，导致模块加载失败。可以尝试清理缓存并删除node_modules后重新安装。
# 清理npm缓存
npm cache clean --force
# 删除node_modules目录和package-lock.json文件
rm -rf node_modules package-lock.json
# 重新安装所有依赖
npm install
步骤4：检查Node.js模块解析机制
了解Node.js的模块查找顺序有助于诊断问题。Node.js会依次从当前目录的node_modules、父目录的node_modules，直至根目录的node_modules中查找模块。确保你的项目结构符合这个规则。对于全局安装的模块，可以通过npm root -g命令查看全局安装路径，并确保该路径在NODE_PATH环境变量中（但此方法已不推荐，优先使用项目本地依赖）。
步骤5：验证包管理器的锁文件
如果团队协作中package-lock.json或yarn.lock文件不同步，可能导致安装的版本不一致。建议将锁文件纳入版本控制，并确保所有成员在安装依赖前使用相同的锁文件。
# 使用package-lock.json精确安装（npm 5+）
npm ci
四、注意事项
在解决问题时，请注意区分模块是项目依赖、开发依赖还是全局依赖。避免将全局模块误当作项目模块来引用。在持续集成（CI）环境中，务必确保构建步骤包含了npm install或yarn install。此外，使用nvm等Node版本管理工具时，要确认当前使用的Node.js版本与项目要求的版本兼容。
五、适用环境
此问题排查方法适用于所有基于CommonJS或ES Modules的Node.js项目环境。