Module Not Found是Node.js模块加载阶段的硬性失败，无法try/catch捕获，必须从根源排查：确认模块拼写与安装状态、验证路径解析（如require.resolve）、区分CJS/ESM规则、检查工作目录及环境一致性，并清理损坏的node_modules和缓存。
模块未找到（Module Not Found）不是运行时可捕获的 JavaScript 异常，而是 Node.js 模块加载阶段的**硬性失败**，发生在代码执行前。它无法用 try/catch 拦截，必须从根源排查和预防。
确认模块是否存在并正确安装
这是最常见原因。Node.js 不会自动安装缺失依赖，必须手动补全：
- 检查报错中提到的模块名是否拼写准确（大小写敏感，尤其在 Linux/macOS 上）
- 运行
npm ls查看是否已安装；若提示empty或missing，说明未装或安装失败 - 执行
npm install（本地依赖）或npm install -g（全局命令类依赖） - 如果是第三方库如
groundingdino，需确认它是否真实发布在 npm 上——部分模型库需通过 GitHub 安装：npm install git+https://github.com/IDEA-Research/GroundingDINO.git
验证路径与模块解析规则
相对路径、扩展名、目录结构都直接影响加载结果：
- 使用
require('./utils')时，Node.js 会依次尝试./utils.js、./utils.json、./utils/index.js；若文件实际叫utils.mjs或utils.ts，就会失败 - 启用 ESM（
"type": "module"）后，import必须带扩展名：import helper from './helper.js'，不能省略.js - 用
node -e "console.log(require.resolve('./xxx'))"直接测试路径能否被解析出真实文件位置，比靠经验更可靠 - 确保当前工作目录是项目根目录（
package.json所在处），否则node_modules无法被向上查找
区分环境与模块类型
很多“找不到”其实是误用场景导致的逻辑错误：
-
fs、path、os是 Node.js 内置模块，在浏览器或 React/Vue 前端组件中直接import必然报错 - Next.js、Fumadocs 等框架中，应将含
fs的逻辑移至app/api/路由或服务端组件（'use server'）中执行 - Webpack/Vite 构建时报
Can't resolve 'fs'，通常意味着配置未正确标记该模块为 node 内置（如 Webpack 的node: { fs: 'empty' }）或构建目标设为了浏览器
修复损坏的依赖状态
有时模块明明装了却仍报错，大概率是缓存或文件系统不一致：
- 删除
node_modules和package-lock.json（或yarn.lock），再重新运行npm install - 清除 npm 缓存：
npm cache clean --force - 检查
npm config get prefix，若指向异常路径（如D:\entg\node.js），需重设并更新系统 PATH - VSCode 中若编辑器报错但终端正常，可能是工作区没从项目根启动，用终端执行
code .重新打开
