VSCode 与 Node.js 协同开发需配置 launch.json、package.json 脚本联动、环境变量隔离及调试入口，否则易出现断点失效、模块找不到、热更不触发等问题。
VSCode 和 Node.js 能各自运行，不等于项目能协同开发——缺了 launch.json、package.json 脚本联动、环境变量隔离或调试入口配置，协作时就会出现“别人能跑，你断点不生效”“本地起得来，CI 报 Cannot find module”“改了代码但热更没触发”这类问题。
launch.json 配置必须匹配实际启动方式
VSCode 不会自动识别你的启动逻辑，比如用 ts-node、nodemon 或 npm run dev，默认的 program 字段只认 node index.js 这种原始方式。
- 如果项目用
npm run start启动，launch.json应设"runtimeExecutable": "npm"+"args": ["run", "start"] - 若用
ts-node src/index.ts，要写"runtimeExecutable": "npx"+"args": ["ts-node", "${workspaceFolder}/src/index.ts"]，且确保ts-node是本地依赖（非全局） - 用
nodemon时，"restart": true必须开启，否则修改后不会自动重载；同时加"console": "integratedTerminal"才能看到实时日志 - 别直接复制网上模板里的
"env": {"NODE_ENV": "development"}—— 如果项目里用dotenv加载 .env，这个env字段反而会覆盖文件内容
package.json scripts 要和 VSCode 任务绑定
多人协作时，靠口头说“先跑 npm run build 再 npm start”不可靠，VSCode 的 tasks.json 可以把常用流程固化下来，并支持一键触发、错误高亮、输出捕获。
- 在
.vscode/tasks.json中定义 task，例如："label": "dev:server"对应"npm run dev"，并设"isBackground": true让它持续运行 - 用
"dependsOn": ["build"]实现串行任务，比如启动前自动编译 TypeScript - 关键字段
"group": "build"或"group": "test"能让这些 task 在 VSCode 的“终端 → 运行任务”菜单里自动归类，比手动敲命令快得多 - 避免在 script 里写
cross-env NODE_ENV=development node index.js—— Windows 下cross-env常因路径空格或权限失败，改用"env": {"NODE_ENV": "development"}更稳
node_modules 和全局路径必须统一管理
不同人装的 node 版本、npm 镜像源、缓存位置不一致，会导致 npm install 结果不同，进而引发“模块找不到”或“ESM/CJS 混用报错”。
- 项目根目录加
.nvmrc（内容如18.16.1），配合nvm use确保 Node 版本一致；不要只靠engines字段，它只警告不拦截 - 所有团队成员统一镜像源：
npm config set registry https://registry.npmmirror.com/，并在package.json的scripts.preinstall里加校验逻辑（如检查npm config get registry输出） - 禁止全局安装开发依赖（如
typescript、eslint），全部走devDependencies；否则 CI 里没全局环境就直接失败 -
node_modules不进 Git，但package-lock.json必须提交——尤其用 npm v8+ 时，lock 文件决定了node_modules的确切结构
最常被忽略的是：VSCode 的内置终端是否读取了你改过的环境变量。改完 PATH 或 npm config 后，必须关掉所有 VSCode 窗口再重开，仅重启终端无效。另外，launch.json 里 env 字段的优先级高于系统环境变量，但低于 .env 文件（如果用了 dotenv），这点在调试跨环境逻辑时极易踩坑。
