VS Code tasks.json options.cwd 指定任务工作目录的配置方法

VS Code 任务默认把工作区根目录当作当前目录。如果构建脚本在 frontend、测试数据在 fixtures，直接运行任务就可能出现“文件不存在”或产物落错位置。稳定的做法是在 .vscode/tasks.json 的任务对象中设置 options.cwd，让命令从目标目录启动；路径优先写成 ${workspaceFolder} 加相对目录，换电脑或换系统时更容易复用。

官方地址：https://code.visualstudio.com/docs/debugtest/tasks

从任务入口打开 tasks.json

先在 VS Code 打开一个工作区，而不是只打开单个文件。选择顶部菜单“终端”→“配置任务”→“从模板创建 tasks.json”，如果文件已经存在，直接打开工作区中的 .vscode/tasks.json。软件教程里的菜单和字段名称可能随语言包变化，但入口仍然围绕“配置任务”和 tasks.json。

下面的片段使用 JSONC 语法，注释是给读者看的配置说明；真正保存时可以保留 VS Code 支持的注释。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "构建前端",
      "type": "shell",
      "command": "npm run build",
      "options": {
        // 让命令从前端目录启动，避免相对路径指向工作区根目录
        "cwd": "${workspaceFolder}/frontend"
      },
      "problemMatcher": []
    }
  ]
}

用 options.cwd 指定任务的启动目录

把配置保存后，重点看三层关系：command 是要执行的命令，args 是传给命令的参数，options.cwd 才是进程启动时的当前目录。不要把 cd frontend && npm run build 硬塞进命令字符串，这种写法会把 shell 语法、引号和 Windows 兼容问题混在一起。

如果目录在工作区根目录下，使用 ${workspaceFolder}/frontend 比写死绝对路径更稳。官方变量参考说明，任务配置支持在 command、args 和 options 中使用变量；Windows 路径中的反斜杠要按 JSON 规则转义，也可以使用 ${pathSeparator} 组织跨平台路径。

运行任务并确认工作目录真的生效

按 ⌘⇧B（Windows/Linux 使用 Ctrl+Shift+B）运行默认构建任务，或选择“终端”→“运行任务”→“构建前端”。确认时不要只看命令是否返回成功：任务终端的当前路径、生成文件的相对位置和任务状态都要对得上。下图是帮助读者识别这些位置的原创界面说明图，不是本机运行截图。

为了让目录可见，可以临时把命令改成输出当前目录的短测试任务；验证结束后再换回构建命令：

{
  "label": "检查前端工作目录",
  "type": "shell",
  "command": "pwd",
  "options": {
    // 这个任务只用于确认启动目录，验证后可删除
    "cwd": "${workspaceFolder}/frontend"
  },
  "problemMatcher": []
}

如果使用 Windows，命令可以改为 cd，但 options.cwd 的配置思路不变。验证通过后，恢复正式任务并检查构建产物是否写入预期目录。

多根工作区和跨平台路径的处理

多根工作区不要猜测根目录。官方变量可用带名称的形式区分文件夹，例如 ${workspaceFolder:frontend}；名称必须与工作区中显示的文件夹名对应。这样一个任务可以明确绑定前端目录，另一个任务绑定后端目录，避免依赖当前活动编辑器。

当任务能打开但相对路径仍错误，按这张清单排查：先确认 cwd 所指目录真实存在；再确认变量展开后是不是目标文件夹；然后区分任务终端的目录和调试配置 launch.json 的运行目录；最后检查脚本是否自己又切换了目录。不要用终端全局 terminal.integrated.cwd 去替代任务级配置。

常见问题

为什么 options.cwd 写了却没有效果？

最常见原因是字段放在了任务外层、JSONC 层级错误，或运行的并不是刚修改的任务。确认 options 位于对应的任务对象内，并从“运行任务”重新选择同一个 label。

options.cwd 能不能直接写绝对路径？

可以，但团队协作和跨平台迁移成本更高。项目内目录优先使用 ${workspaceFolder}；只有目录确实不属于工作区时，才考虑绝对路径，并同步处理不同系统的路径差异。

cwd 和环境变量是一回事吗？

不是。cwd 决定进程从哪里启动，options.env 决定进程收到哪些环境变量；两者可以同时配置，但解决的是不同问题。