VSCode终端能运行node -v但执行脚本报Cannot find module，说明Node.js环境正常，问题在于模块查找路径不匹配：可能未安装、安装位置错误、package.json声明缺失、锁文件不一致、包管理器混用、ESM路径解析失败（需带扩展名/大小写严格）、调试配置路径错误、插件依赖未单独安装，或VSCode未从终端启动导致环境变量未继承。
VSCode终端能运行 node -v，但执行脚本时报 Cannot find module，说明 Node.js 环境本身正常，问题出在模块查找路径没对上——不是没装，而是没找对地方。
npm install 后仍报 Cannot find module
这通常意味着 node_modules 里压根没有那个包，或安装位置和当前运行路径不匹配。
- 运行
npm ls（比如npm ls axios），如果输出empty或直接报错，说明它不在当前项目的依赖树里 - 检查
package.json的dependencies或devDependencies字段，确认该模块已声明；漏写字段会导致npm install忽略它 - 删掉项目根目录下的
node_modules和package-lock.json，再跑一次npm install——锁文件不一致是静默故障最常见原因 - 如果你用的是
yarn workspaces或pnpm，别混用npm install；必须在终端里明确执行yarn install或pnpm install
require('./utils') 报错但文件明明存在
这是路径解析失败，和包管理无关。Node.js 对相对路径极其敏感，尤其在 ESM 模式下。
- ESM 中
import必须带扩展名：import utils from './utils.js'，省略.js一定会报错 - 大小写和拼写必须完全一致：Linux/macOS 下
Utils.js≠utils.js，VSCode 编辑器可能不提示，但 Node.js 运行时会崩 - 用
node -e "console.log(require.resolve('./utils'))"直接验证路径能否解析；报错信息里会列出它实际尝试的完整路径，比猜更准 - 如果
./utils是个目录，确保里面有index.js或符合package.json#main的入口文件
调试时 launch.json 配置正确却找不到本地模块
VSCode 调试器默认不自动注入 node_modules 路径，尤其当 program 指向的是未编译源码或子目录时，路径就断了。
-
launch.json中的program必须指向可执行的 JS 入口，推荐填"${workspaceFolder}/dist/index.js"或"${workspaceFolder}/index.js"，不能是src/index.ts这类源码路径 - 避免在
env里手动加NODE_PATH，它会覆盖默认查找逻辑，反而让相对路径失效 - 如果是 TypeScript 项目，确认
tsconfig.json的outDir和rootDir匹配，并已运行tsc或npm run build - ESM 项目必须在
package.json里加"type": "module"，否则import语句会被当 CommonJS 处理，路径规则完全不同
插件开发时提示 Cannot find module 'xxx'
VSCode 插件的依赖和你的业务项目完全隔离，插件自身的 node_modules 必须单独安装。
- 打开插件源码目录（不是你写的业务代码目录），确认里面有没有
node_modules；没有就进该目录运行npm install - 检查插件目录下的
package.json，确认dependencies或devDependencies里真有那个模块（比如"vscode-languageclient"） - 如果用了
pnpm，别误删node_modules/.pnpm缓存目录——旧缓存可能导致类型定义加载错误 - 改完后必须彻底退出 VSCode（不只是 Reload Window），否则扩展主机进程仍运行旧环境
最容易被忽略的一点：VSCode 启动方式决定它能不能继承完整的 shell 环境变量。从 Dock 或开始菜单直接启动，~/.zshrc 或 nvm 初始化代码根本不会执行；务必从终端用 code . 打开项目，才能确保 PATH、node_modules 查找路径、甚至 npm config get prefix 都一致。
