在 VSCode 中开发 Node.js 应用，很多奇怪的问题并不来自代码逻辑，而是编辑器没有正确继承系统里的 Node.js 运行环境。比如你已经通过安装包装好 Node.js，在系统终端执行 node -v 能看到版本号，但 VSCode 集成终端却提示找不到命令。或者调试器能启动进程，断点却始终不命中。这些问题大多可以通过统一环境变量、理解调试配置和调整项目设置来解决。下面先把 VSCode 与 Node.js 的协作关系拆开，再逐项给出操作要点和排查方法。
一、环境准备：让 VSCode 准确识别 Node.js
VSCode 自身不携带 Node.js 运行时，它通过集成终端和调试器调用系统安装的 Node.js。因此环境变量 PATH 的配置直接决定终端能否找到 node 和 npm。安装 Node.js 时，Windows 安装包通常会自动把安装目录写入 PATH，但如果你选择自定义安装，或使用 nvm 管理多版本，就需要额外确认。macOS 和 Linux 用户从官网下载二进制包后，也需要把 bin 目录加入 PATH。最直接的检查方式是在 VSCode 集成终端中运行 node -v 与 npm -v。
node -v npm -v which node
如果系统终端正常而 VSCode 终端异常，先完整退出并重启 VSCode。Windows 下 GUI 启动的编辑器不会实时继承修改后的系统环境变量，重启后才会刷新。如果仍然异常，可以在用户 settings.json 中给集成终端追加 PATH。这里给出 Windows 示例，注意路径中的反斜杠必须原样保留。
{
"terminal.integrated.env.windows": {
"PATH": "C:\\Program Files\\nodejs;${env:PATH}"
}
}
为了避免多人协作时因为 Node.js 版本不同而出现兼容问题，可以在 package.json 中声明 engines 字段。配合 .nvmrc 文件还能让使用 nvm 的开发者快速切换版本。VSCode 不会自动强制版本，但可以在终端里通过 node -v 校验是否匹配。这个习惯比出现问题后再排查更省时间。
{
"engines": {
"node": ">=18.0.0"
}
}
二、运行与调试：从终端命令到 launch.json
入门阶段通常直接在集成终端里执行 node 加文件名。集成终端的好处是当前目录与工作区一致，省去手动 cd 的麻烦。进入项目目录后执行 node app.js 即可。如果项目依赖 npm 包，记得先执行 npm install。可以把启动命令写入 package.json 的 scripts 字段，之后用 npm start 或 npm run dev 统一启动。这样做的好处是团队不需要记住入口文件路径。
{
"scripts": {
"dev": "node src/index.js",
"start": "node src/index.js"
}
}
终端运行适合查看日志，但遇到需要观察变量和逐步执行的问题时，就要使用 VSCode 的调试面板。点击左侧运行和调试图标，创建 launch.json 文件，选择 Node.js 环境。launch.json 中最重要的字段是 type、request、program 和 cwd。type 必须为 node，request 为 launch 表示启动新进程，program 指向入口脚本。cwd 指定程序运行时的工作目录，默认可以使用工作区变量。
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "启动 Node.js 程序",
"program": "${workspaceFolder}/src/index.js",
"cwd": "${workspaceFolder}",
"env": {
"NODE_ENV": "development"
},
"console": "integratedTerminal"
}
]
}
配置好 launch.json 后，在代码行号左侧点击可以打断点，然后按 F5 启动调试。调试工具栏支持继续、单步跳过、单步进入和重启。若断点显示灰色或提示未绑定，通常是实际运行的源码与打开的源码不是同一份。比如程序读取的是 dist 目录里的编译产物，而你在 src 目录打断点。这时需要调整 program 或使用 sourceMap。对纯 JavaScript 项目，保持路径一致即可。
三、智能提示与工程化配置
VSCode 对 Node.js 核心模块有基础补全，但项目内模块和第三方包需要更明确的解析依据。在根目录放置 jsconfig.json 可以告诉编辑器源码范围、模块规范和编译选项。对于 CommonJS 项目，可以设置 module 为 commonjs；如果使用 import 语法，则改为 esnext 或 node16。
{
"compilerOptions": {
"module": "commonjs",
"target": "es2022",
"checkJs": true,
"resolveJsonModule": true
},
"exclude": ["node_modules", "dist"]
}
开启 checkJs 后，VSCode 会对 JavaScript 代码做轻量类型检查，能提前发现未定义变量和错误参数数量。对 TypeScript 项目，jsconfig 被 tsconfig.json 取代。第三方包类型提示一般来自包内自带的类型声明或 @types 包。某个依赖没有补全时，优先检查是否安装了对应 @types 包，而不是怀疑 VSCode 损坏。
大型项目中 node_modules 目录会严重影响文件搜索和监视性能。可以在 settings.json 中把 node_modules 和 dist 排除在搜索范围之外，同时减少文件监视器扫描的路径。这样编辑器响应更快，也不会因为巨量文件变化频繁触发索引。
{
"search.exclude": {
"**/node_modules": true,
"**/dist": true
},
"files.watcherExclude": {
"**/node_modules/**": true,
"**/dist/**": true
}
}
如果使用 ESM 模块，要确保 package.json 中 type 字段为 module，或者文件使用 .mjs 扩展名。ESM 与 CommonJS 在路径导入、__dirname 等内置变量上存在差异。VSCode 的智能提示会根据模块规范调整，所以配置错模块类型时，经常会出现 import 报错或 require 补全异常。这也是初学者容易忽略的配置点。
四、常见疑问与避坑指南
第一个高频问题是 node 不是内部或外部命令。这几乎都是 PATH 问题。可以先在系统终端中运行 where node（Windows）或 which node（macOS/Linux）查看实际路径，再回 VSCode 终端检查。若系统终端能识别，重启 VSCode；若仍不行，在 settings.json 里为集成终端添加环境变量。不要反复重装 Node.js，重装并不能解决 PATH 未生效的问题。
{
"terminal.integrated.env.windows": {
"PATH": "C:\\Program Files\\nodejs;${env:PATH}"
}
}
第二个常见问题是 nvm 切换版本后 VSCode 仍用旧版本。nvm 通过修改 shell 配置文件来切换，VSCode 图形界面启动时可能没有加载这些配置。可以先在系统终端切换后，完全退出 VSCode 再打开。也可以在 VSCode 集成终端手动执行 nvm use 命令。更稳妥的方式是在项目中放 .nvmrc，每次打开终端执行 nvm use。
nvm use lts
第三个问题是修改代码后运行结果不变。通常是旧进程没有退出，或者使用了 nodemon 之外的方式启动。直接 node app.js 启动的进程不会监视文件变化，修改后需要手动重启。可以使用 nodemon 作为开发依赖，将启动脚本改为 nodemon src/index.js，保存文件后自动重启。如果使用了调试模式，按调试工具栏的重启按钮也可以加载新代码。
{
"scripts": {
"dev": "nodemon src/index.js"
}
}
第四个问题是 require is not defined 或 import 无法使用。根因是模块规范混淆。CommonJS 使用 require 和 module.exports，ESM 使用 import 和 export default。一个项目不要混用两种规范，除非清楚 .cjs 和 .mjs 的区别。在 package.json 中设置 type 字段后，所有 .js 文件都会按对应规范解析。修改 type 字段后要重启调试进程，否则旧模块仍可能缓存。
{
"type": "module"
}
把这些配置沉淀到项目模板中：固定 Node 版本、写清启动脚本、准备 launch.json 和 jsconfig.json、排除 node_modules。新成员打开项目后只需安装依赖并运行，不必反复排查环境。对 VSCode 而言，它只是前端工具，真正的运行环境仍然是 Node.js，所以遇到问题时先分清是编辑器配置问题、终端环境问题还是代码逻辑问题，定位会快很多。