验证node.js安装成功的三个核心命令是node -v、npm -v和npm config get prefix；分别用于确认node.js运行时、包管理器及全局模块路径是否正确配置。
能跑 node 命令、npm 可用、VSCode 能对当前 JS 文件断点调试，这三件事成立，环境就算搭稳了——其余都是优化项，不是门槛。
验证 node 和 npm 是否真正可用（别跳过）
很多人在 VSCode 里点 F5 报错 Cannot find runtime 'node'，第一反应是“VSCode 配置错了”，其实 90% 是系统级环境没通。必须在系统终端（Windows 的 cmd/PowerShell、macOS/Linux 的 iTerm/Terminal）里执行：
node -v npm -v
如果报 'node' is not recognized 或类似错误，说明 Node.js 没进系统 PATH：
- Windows：LTS 安装时务必勾选
Add to PATH；若漏了，手动把安装路径（如C:\Program Files\nodejs）加到系统环境变量Path，然后重启所有终端窗口 - macOS/Linux：用
nvm安装的，检查source ~/.nvm/nvm.sh是否已写入~/.zshrc或~/.bash_profile，并新开终端验证 - 路径含中文或空格（如
D:\我的软件\nodejs）会导致npm静默失败，务必避开
VSCode 内置调试器直接可用，无需额外插件
VSCode 自带 Node.js 调试支持，Node.js Extension Pack 或 Debugger for Node.js 这类插件现在已过时，装了反而可能干扰调试流程。
确认 node -v 和 npm -v 都成功后，只需三步：
- 新建项目文件夹，创建
index.js，写console.log('ok'); - 按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Debug: Open Configuration，选择Node.js → Current File - VSCode 自动生成
.vscode/launch.json，其中"program": "${file}"表示运行当前打开的文件
此时在行号左侧单击设断点，按 F5 即可启动。若仍失败，一定是上一步的环境没配好，不是 VSCode 设置问题。
多文件夹项目要用 .code-workspace 管理路径别名与配置隔离
当项目涉及前后端分离、monorepo 或跨目录依赖（比如 import utils from '@/utils'），靠单个文件夹打开无法解决路径别名解析和设置污染问题。必须用 .code-workspace 文件聚合多个路径并统一管理。
例如，你有三个不连续目录：./frontend、../shared、~/configs，创建 my-project.code-workspace：
{
"folders": [
{ "path": "./frontend" },
{ "path": "../shared" },
{ "path": "~/configs" }
],
"settings": {
"typescript.preferences.importModuleSpecifier": "relative",
"javascript.preferences.importModuleSpecifier": "relative"
}
}
这个文件能：
- 让 VSCode 正确识别
@/、~/这类别名（配合项目内tsconfig.json或jsconfig.json的compilerOptions.baseUrl和paths） - 避免不同项目间的
settings.json冲突 - 把工作区配置纳入 Git，新成员双击该文件就能复现完整开发视图
路径别名解析失败？检查 jsconfig.json / tsconfig.json 是否生效
VSCode 对路径别名的支持不依赖插件，但必须有对应配置文件且位于工作区根目录下。常见错误是：
- 只在
./frontend里放了jsconfig.json，但工作区根是./，VSCode 找不到 -
jsconfig.json中写了"baseUrl": "./src"，但没配"paths"，导致@/utils无法映射 - 用了 TypeScript 但没装
typescript本地依赖，tsconfig.json不被识别
一个最小可行的 jsconfig.json 示例：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@/utils/*": ["src/utils/*"]
}
},
"include": ["src/**/*"]
}
改完保存后，VSCode 会自动重载类型服务——不需要重启编辑器，但必须确保该文件在 .code-workspace 所定义的某个 folder.path 下。
最常被忽略的一点：路径别名只是编辑器提示和跳转支持，require() 或 import 运行时是否能解析，取决于你的打包工具（Webpack/Vite）或 Node.js 的 --loader 配置，VSCode 不参与运行时行为。别把编辑器提示正常当成代码一定能跑通。
