必须先确保 VSCode 内置终端能直接执行 node 和 npm，否则所有自动化脚本均失败；需验证版本号、正确配置 PATH、避免路径含空格或中文，并在 tasks.json 中用 npx 替代全局 npm、显式指定 shell 和环境变量。
必须先让 node 和 npm 在 VSCode 内置终端里能直接执行，否则所有自动化脚本都会失败。
验证 node 是否真可用
很多人卡在这一步却以为是脚本或配置问题。打开 VSCode 内置终端（Ctrl + `），运行：
node -v<br>npm -v
两个命令都必须输出版本号。如果报 command not found: node，说明 VSCode 没继承系统 PATH —— 这和插件、launch.json、tasks.json 都无关。
- macOS/Linux：改完
~/.zshrc或~/.bash_profile后，必须完全退出 VSCode 并重启；更稳妥的是在终端中用code .启动项目 - Windows：安装 Node.js 时没勾选
Add to PATH，就去“系统属性 → 环境变量”手动把C:\Program Files\nodejs\加进系统 PATH，然后彻底关闭 VSCode - 路径含空格或中文（如
C:\Program Files\nodejs\或D:\软件\nodejs\）会导致某些 shell 初始化失败，建议重装到纯英文无空格路径（如C:\nodejs\）
tasks.json 中避免 npm 全局命令失效
VSCode 的 tasks.json 默认不加载 shell 初始化文件，也不继承项目级 .env，更不会自动使用 node_modules/.bin 下的本地二进制——所以直接写 "command": "npm run deploy" 很可能报 npm: command not found 或调用错版本的 node。
- 用
npx --no-install替代全局npm：例如"command": "npx --no-install cross-env NODE_ENV=production node scripts/deploy.js" - 显式指定 shell 可执行路径：
"shell": { "executable": "/bin/zsh", "args": ["-c"] }（macOS/Linux）或"shell": { "executable": "cmd.exe", "args": ["/c"] }（Windows） - 手动注入环境变量：
"env": { "NODE_ENV": "production", "API_URL": "https://api.example.com" }，别依赖dotenv自动加载 - 确保
.vscode/tasks.json放在项目根目录，且结构合法：每个 task 至少含"label"和"type": "shell"，加"group": "build"才会出现在Ctrl+Shift+P → Tasks: Run Task列表里
调试自动化脚本时 program 路径必须指向真实 JS 文件
如果你在 launch.json 里配了调试任务，但点 F5 报 Cannot launch program because corresponding JavaScript cannot be found，大概率是 program 字段写错了。
-
"program": "${file}"仅适用于单文件临时调试；正式脚本应明确写成"program": "${workspaceFolder}/scripts/deploy.js" - 若脚本由 TypeScript 编译生成（如
dist/deploy.js），program必须指向编译后的.js，不是.ts源码；同时tsconfig.json中需开启"sourceMap": true - ESM 项目必须在
package.json中声明"type": "module"，否则调试器按 CommonJS 解析，import会直接报错 - 别乱填
runtimeExecutable—— 除非你用nvm管理多版本且需锁定路径（如"runtimeExecutable": "~/.nvm/versions/node/v18.18.2/bin/node"），否则默认行为更稳定
Code Runner 插件不适合跑自动化脚本
code-runner 默认命令是 node $fileName，它不处理编码、模块类型、环境变量，也不支持 process.stdin 输入流，对自动化脚本来说太脆弱。
- Windows 中文路径下乱码？改
settings.json中的code-runner.executorMap："node -r utf-8 $fileName" - ESM 报
Cannot use import statement outside a module？先确认package.json有"type": "module"，再把 executor 改成："node --experimental-specifier-resolution=node $fileName" - 遇到
readline或process.stdin.on('data', ...)就卡死？这是code-runner的固有限制，换用内置终端手动执行或 F5 调试 - 真正需要串行执行（比如先构建再部署）时，
dependsOn不等于等待完成 —— 必须加"dependsOrder": "sequence"和"isBackground": false
复杂脚本的入口路径、模块类型、环境变量、输入输出流，任何一个环节没对齐，就会在看似“配置完成”后突然失败。最省事的做法：所有自动化逻辑统一走 npm script + tasks.json + 内置终端验证，绕过 code-runner 和模糊的快捷键触发。
