先说一个核心判断：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 会回退到 %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 里那几行配置，改错一个字段，断点就永远打不进去。
