直接写“npm run deploy”在VSCode任务中失败，是因为tasks.json不继承shell的PATH、不加载项目级.env、也不自动使用node_modules/.bin下的本地二进制，导致command not found或node版本不匹配；应改用npx --no-install调用本地包，并显式指定shell路径和env字段。
为什么直接写 npm run deploy 在 VSCode 任务里会失败
VSCode 的 tasks.json 不继承 shell 的 PATH、不加载项目级 .env、也不自动使用 node_modules/.bin 下的本地二进制。你看到的 command not found 或 node version mismatch，几乎都源于这个隔离环境。
常见错误现象：npm: command not found（尤其在 macOS/Linux 的 zsh 下）、cross-env is not recognized（Windows PowerShell 默认禁用脚本）、Cannot find module 'dotenv'（.env 没被注入）。
- 别依赖全局
npm，改用npx --no-install调用本地包，例如"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字段，哪怕你用了dotenv："env": { "NODE_ENV": "production", "API_URL": "https://api.example.com" }
tasks.json 必须放对位置且结构合法
VSCode 只读取工作区根目录下 .vscode/tasks.json，文件名不能是 task.json、Tasks.json 或带空格，路径也不能嵌套在子文件夹里。
容易踩的坑："version": "2.0.0" 是固定字符串，不是语义版本；漏掉 "group": "build" 或 "problemMatcher"，VSCode 就不把它当可运行任务——你在 Ctrl+Shift+P → Tasks: Run Task 里根本看不到它。
- 确认文件路径：必须是
/your-project/.vscode/tasks.json - 每个 task 至少要有
"label"和"type": "shell" - 若想让它出现在“运行任务”列表顶部，加
"group": "build"或"group": "deploy"
如何让构建和部署真正串行执行
写了 "dependsOn": ["build"] 不等于部署等构建完再开始——默认是并发启动，尤其当 build 是异步命令（如 vite build）时，部署可能在 dist 目录生成前就去读它。
关键不是依赖关系本身，而是“结束信号”。VSCode 靠 problemMatcher 或进程退出码判断任务是否完成。
- 显式设置
"isBackground": false（即使默认是 false，也建议写出来） - 加上
"dependsOrder": "sequence"，缺了这句，dependsOn就只是顺序启动，不是顺序等待 - 如果依赖的是监听类任务（如
tsc --watch），必须配"problemMatcher": ["$tsc-watch"]并靠输出匹配endOfLine触发结束
调试部署脚本时为什么断点不生效
VSCode 的 Node.js 调试器只 attach 到明确由 node 启动的进程，而 tasks.json 中的 shell 命令默认不启用 debug 模式。你设了断点，但脚本是直接跑起来的，没走调试通道。
解决办法不是改 tasks.json，而是把部署逻辑封装成可调试的 .js 文件，再用 launch.json 单独调试它：
- 把部署逻辑抽到
scripts/deploy.js，用node --inspect-brk scripts/deploy.js启动 - 在
launch.json中新增一个配置，"program"指向该文件，"console": "integratedTerminal" - 这样你既能设断点，又能看到完整 stdout/stderr，比在任务里黑盒执行可靠得多
真正复杂的地方不在语法，而在环境隔离——VSCode 任务不共享你的终端上下文，也不模拟 npm run 的执行链路。每一步都要手动补全，少一个 env、漏一个 dependsOrder，就卡在半路。
