直接写“npm run build”在tasks.json中大概率失败，因为vscode任务系统不继承shell的path、不加载项目级.env、也不自动使用node_modules/.bin下的本地二进制；应改用npx --no-install调用本地包，并显式指定shell路径和env字段。

直接在 VSCode 里写 npm run build 当作任务运行，大概率失败——不是脚本写错了，而是 VSCode 的 tasks.json 根本不认你终端里能跑的那些命令。

为什么 npm run build 在 tasks.json 里总报 command not found

VSCode 的任务系统不继承 shell 的 PATH，也不加载项目根目录下的 .env，更不会自动用 node_modules/.bin 里的本地二进制。所以你在终端里能跑的 npm，在 task 里很可能根本找不到。

• npm: command not found（尤其 macOS/Linux 的 zsh 下）
• cross-env is not recognized（Windows PowerShell 默认禁用脚本）
• Cannot find module 'dotenv'（.env 没注入，环境变量全空）

别依赖全局 npm，改用 npx --no-install 调本地包，它会自动从 node_modules/.bin 找命令，且不重装依赖。

怎么写一个真正能跑的 build task

必须显式指定 shell 路径、补全环境变量、用 npx 替代 npm run。

• "command": "npx --no-install webpack --mode production"（直接调构建工具，绕过 package.json scripts）
• 或 "command": "npx --no-install npm run build"（仍走 script，但确保用本地 npm）
• "shell": { "executable": "/bin/zsh", "args": ["-c"] }（macOS/Linux）
• "shell": { "executable": "cmd.exe", "args": ["/c"] }（Windows）
• "env": { "NODE_ENV": "production" }（手动注入关键变量）

漏掉 "group": "build"，这个 task 就不会出现在 Ctrl+Shift+P → Tasks: Run Task 列表里。

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

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

下载

dependsOn 不等于串行执行，这是最常被忽略的坑

写了 "dependsOn": ["build"]，部署任务还是可能在 dist/ 目录生成前就启动——因为默认是并发，不是等待。

• 加 "isBackground": false（显式声明非后台任务）
• 加 "dependsOrder": "sequence"（缺了这句，dependsOn 只是顺序触发，不是顺序阻塞）
• 靠 "problemMatcher" 或进程退出码判断完成，不是靠“看起来像跑完了”

如果 build 脚本本身是异步的（比如 vite build），还要确认它最终会正常 exit，否则 VSCode 会一直等下去。

tasks.json 必须放对位置且结构合法

VSCode 只读取工作区根目录下的 .vscode/tasks.json，路径错一点、文件名多一个空格、或者放在子目录里，整个文件就失效。

• 文件名必须是 tasks.json，不能是 task.json 或 Tasks.json
• 每个 task 至少要有 "label" 和 "type": "shell"
• "version": "2.0.0" 是固定字符串，不是语义版本号，写错就解析失败
• 想让它出现在任务列表顶部，加 "group": "build" 或 "group": "deploy"

真正容易被忽略的，是 problemMatcher ——没有它，VSCode 就没法把构建错误定位到具体行号，报错信息只有一堆文字，调试成本翻倍。