VSCode找不到node命令的根本原因是环境变量未继承：macOS/Linux因Dock启动跳过shell配置加载，Windows因Node安装未勾选“Add to PATH”；需分别通过终端启动code、重装Node或手动配置PATH解决。

VSCode 启动后找不到 node 命令

这不是插件没装好，也不是 VSCode 故障，而是环境变量根本没传进来。终端里能跑 node -v，但 VSCode 内置终端报 command not found: node，99% 是启动方式绕过了 shell 初始化逻辑。

• macOS/Linux：从 Dock 或 Spotlight 启动 VSCode 时，~/.zshrc 或 ~/.bash_profile 不会被加载；确认 which node 输出的路径（比如 /opt/homebrew/bin/node）已加进 shell 配置文件的 PATH，改完必须重启 VSCode —— 更稳妥的做法是直接从终端运行 code --no-sandbox .
• Windows：Node.js 安装时没勾选 “Add to PATH” 是最常见原因；打开系统环境变量设置，把 C:\Program Files\nodejs\ 明确加到“系统变量”或“用户变量”的 PATH 中；重装 Node.js 时务必勾选该选项
• 验证方式：在 VSCode 内置终端（Ctrl + `）中执行 node -v，有输出才算真正生效；没通过这步，后续所有调试、运行、插件功能都可能失效

code-runner 执行 JS 脚本时乱码、卡死或报 Cannot use import statement

默认的 code-runner 执行命令太简单，不处理编码、模块类型和标准输入流，尤其在中文路径、ESM 项目或需要交互的场景下极易出问题。

• Windows 中文路径乱码：在 VSCode 设置中搜索 code-runner.executorMap，把 javascript 对应值改成：node -r utf-8 $fileName
• ESM 报错：确保项目根目录 package.json 中有 "type": "module"，再把 executor 改成：node --experimental-specifier-resolution=node $fileName
• process.stdin 导致假死：code-runner 不支持交互式输入；要么换用内置终端手动运行，要么改用调试模式（F5），后者能正确挂载 stdin/stdout

断点不命中，或提示 Cannot launch program because corresponding JavaScript cannot be found

这不是代码写错了，而是调试器找不到真实可执行的 JS 文件，或者源映射（source map）没对齐。常见于 TypeScript 编译、Webpack 打包、或 ESM/CJS 混用项目。

用于自动切换项目中适合的node 版本

根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。

下载

• TS/打包项目：确保 launch.json 中 program 指向的是编译后或打包后的入口文件（如 ./dist/index.js），不是 .ts 源文件
• ESM/CJS 混用：检查 package.json 的 "type" 字段是否与实际执行环境一致；若用 require() 加载 ES 模块，会直接崩溃，调试器也无法解析
• Source map 错位：TypeScript 项目需在 tsconfig.json 中启用 "sourceMap": true 和 "inlineSources": true，且 launch.json 中设置 "sourceMaps": true

调试时无法读取 .env 文件或依赖注入失败

VSCode 调试器默认不加载 .env，也不会自动执行 npm start 类脚本中的环境变量设置逻辑，导致 process.env 为空或缺失关键配置。

• 手动注入：在 launch.json 的配置项中添加 "env" 字段，例如："env": { "NODE_ENV": "development", "PORT": "3000" }
• 自动加载 .env：使用 dotenv 包，在入口文件顶部加 require('dotenv').config()；注意路径，默认只读取项目根目录下的 .env
• 避免硬编码：不要在 launch.json 里写死敏感值；生产环境变量应由部署平台注入，本地调试仅用于开发流程验证

真正卡住人的地方往往不是 Node.js 本身，而是环境变量继承、模块系统边界、以及调试器对构建产物的理解程度。每一步验证都要落在具体命令和输出上，而不是凭感觉跳过。