先说一个核心判断：VSCode 和 Node.js 的整合本身非常成熟，但默认安装后直接打开 app.js 按 F5 调试，十有八九会失败。问题不在环境没装好，而是调试配置缺失或者路径没对齐。下面把几个最常踩的坑掰开了说。
node -v 能用，但 VSCode 里 node app.js 报错：先查终端 Shell 和工作区路径
来，先排查一个经典场景：命令行里 node -v 跑得好好的，但 VSCode 内置终端执行 node app.js 却提示 command not found 或者 Cannot find module。这种别扭，说到底是一个路径作用域的问题——VSCode 终端没有继承系统 PATH，或者是当前打开的文件夹根本不是项目根目录。
怎么解决？三步走：
- 先看 VSCode 内置终端用的是哪个 Shell。Windows 默认 PowerShell，有时候它会漏掉 Node 的 PATH（尤其手动改过 npm 全局路径的）。在终端右上角下拉菜单里，可以切换成
Command Prompt或者Git Bash，试一下。 - 务必用
File → Open Folder打开整个项目文件夹，而不是单个.js文件。否则node_modules和package.json根本不会被识别，require 自然找不到。 - 在终端里跑一下
where node（Windows）或which node（macOS/Linux），对比命令行和 VSCode 内置终端的输出。如果不一致，说明 Shell 环境隔离了，需要手动统一。
launch.json 配错了，F5 启动必然失败：别直接照搬模板
VSCode 的调试流程依赖 .vscode/launch.json，但自动生成的模板经常塞一堆过时字段（比如 outFiles），还有硬编码的路径。一运行就是 Cannot launch program; the specified configuration is invalid，然后断点永远打不进去。
其实最简单的可用配置，只保留三个字段就够了：type: "pwa-node"（新版推荐）、request: "launch"、以及 runtimeExecutable。Windows 全局安装路径可以写成 "${env:USERPROFILE}AppDataRoamingnpmnode.exe"，项目本地安装则用 "${workspaceFolder}/node_modules/.bin/node"。其他什么 outFiles、sourceMaps、preLaunchTask，除非你在用 TypeScript 或 Webpack，否则全部删掉。
另外提一个常见误解：如果项目用了 nodemon，不要在 launch.json 里写 nodemon app.js。改用 runtimeArgs——比如 TypeScript 场景可以写成 "runtimeArgs": ["-r", "ts-node/register", "app.ts"]，或者直接用 tasks.json 来管理启动流程。
npm 全局模块在 VSCode 里找不到：PATH 和权限双坑
好，下一个坑：npm install express -g 运行成功，但项目里 require('express') 还是报 Cannot find module 'express'。原因很简单——全局安装的模块不会自动加入项目 node_modules，而且 VSCode 可能根本没有权限读取管理员级的安装路径。
原则只有一个：全局模块只适合 CLI 工具（比如 http-server、json-server），绝不用于 require()。项目依赖一律用 npm install express（不带 -g）。
如果你非要让全局 Express 启动服务，那就必须在 launch.json 里显式指定 runtimeExecutable，指向全局 node.exe，同时确保 env 字段包含了完整 PATH："env": {"PATH": "${env:PATH}"}。但说实话，不推荐这么绕。
还有一个容易被忽略的细节：Windows 上用管理员身份运行 VSCode 才能访问 C:Program Filesodejs 下的全局 bin，普通用户启动的 VSCode 会 fallback 到 %APPDATA%pm，路径完全不一样。
上线前忽略的环境差异：process.env.NODE_ENV 和 package.json scripts
最后一个坑，也最隐蔽：本地 npm start 一切正常，部署到服务器后直接崩，错误日志里反复出现 Cannot find module 'dotenv' 或者 PORT undefined。问题不在代码，而在执行上下文和脚本定义。
这里有几个关键点：
process.env.NODE_ENV在 VSCode 调试中默认是undefined，不是development。必须在launch.json的env字段里手动加："env": {"NODE_ENV": "development"}。package.json中的scripts是上线唯一可信入口，VSCode 调试不应该绕过它。最佳实践是先把启动命令写进"start": "node app.js"，然后在launch.json里把runtimeExecutable指向npm，args设为["start"]。- 特别注意：生产环境严禁依赖
devDependencies，比如nodemon、eslint。部署时用npm install --production，确保node_modules里只有dependencies——否则一跑就缺模块。
真正卡住人的，从来不是“怎么装”，而是“哪个环节的路径、环境、作用域没对齐”。VSCode 和 Node.js 的整合点其实很薄，但每一层都得严丝合缝——尤其是 launch.json 里那几行配置，改错一个字段，断点就永远打不进去。
