# VS Code tasks.json 完整参数说明文档

## 文档说明

本文档覆盖 `tasks.json` 顶层配置、单任务全部字段、跨平台配置、内置变量、完整可运行示例，适配 Windows MSVC + Boost b2 C++ 构建场景。

## 一、tasks.json 顶层根字段

```
{
  "version": "2.0.0",
  "tasks": [],
  "inputs": []
}
```

表格

| 字段 | 作用 |
| --- | --- |
| `version` | 任务配置标准版本号，固定填写 `2.0.0`，不可修改 |
| `tasks` | 数组，存放所有构建任务，每一项为独立编译 / 清理脚本 |
| `inputs` | 自定义交互式输入配置，用于弹窗手动传入参数（进阶） |

## 二、单个任务核心配置（tasks 数组内对象）

### 1. 基础标识字段

#### label（必填）

任务显示名称，两处关键用途：

1. `Ctrl+Shift+B` 下拉列表展示名称
2. `launch.json` 的 `preLaunchTask` 通过该名称绑定编译任务

```
"label": "Boost Build Debug"
```

#### type（任务执行类型，三选一）

表格

| 取值 | 适用场景 | 特点 |
| --- | --- | --- |
| `shell` | Windows cmd/PowerShell、Linux bash | 支持 `&&`、管道等多条命令串联，C++ Windows 首选 |
| `process` | 直接运行 exe 可执行文件（b2.exe/cl.exe） | 不经过系统 shell，性能更高，不支持多条命令拼接 |
| `npm` | 前端 Node 项目 | C++ 开发无需使用 |
| `cppbuild` | 用于 C/C++ 项目的编译任务 |  |



#### command

要执行的命令 / 可执行文件：

- `type: shell`：可简写命令名 `b2`、`cl`
- `type: process`：必须写完整相对路径 `./b2.exe`
- `type:cppbuild`: 可以写`cl.exe`

#### args

命令行参数数组，每个参数单独一项，自动分隔空格，无需手动拼接空格。
示例：`b2 toolset=msvc variant=debug stage`

```
"args": ["toolset=msvc", "variant=debug", "stage"]
```

### 2. 构建分组 group（快捷键绑定）

控制 `Ctrl+Shift+B` 行为

```
"group": {
  "kind": "build",
  "isDefault": true
}
```

- `kind: "build"`：归类为构建任务，快捷键调出
- `kind: "test"`：归类为测试任务
- `isDefault: true`：按下 `Ctrl+Shift+B` 直接执行该任务

### 3. problemMatcher 编译错误捕获（关键功能）

将编译器报错、警告同步到 VSCode「问题」面板，点击直接跳转代码行。
内置模板直接使用：

表格

| 模板值 | 适用编译器 |
| --- | --- |
| `$msCompile` | MSVC cl.exe、Boost b2（Windows C++） |
| `$gcc` | MinGW GCC、Linux GCC |

自定义模式：自行编写正则解析日志（极少使用）

```
"problemMatcher": "$msCompile"
```

### 4. options 运行环境配置

控制任务工作目录、临时环境变量

#### cwd

任务执行的工作目录，命令在此路径运行

```
"options": {
  "cwd": "${workspaceFolder}"
}
```

#### env

仅当前任务生效的临时环境变量，不修改系统全局环境

```
"options": {
  "env": {
    "PATH": "D:/boost/stage/lib;${env:PATH}",
    "BOOST_ROOT": "D:/boost"
  }
}
```

### 5. 跨平台差异化配置 windows /linux/osx

三套系统独立配置，优先级高于外层通用配置，Windows 用于自动加载 MSVC 编译环境。

```
"windows": {
  "options": {
    "shell": {
      "executable": "cmd.exe",
      "args": ["/C", "VsDevCmd.bat &&"]
    }
  }
},
"linux": {},
"osx": {}
```

### 6. shell 终端自定义（仅 type=shell 生效）

```
"shell": {
  "executable": "cmd.exe",
  "args": ["/C"],
  "env": {}
}
```

- `executable`：指定终端程序 cmd /powershell/bash
- `args`：终端启动参数，`/C` 代表执行完命令关闭窗口

### 7. presentation 终端展示样式

控制任务终端弹窗行为

```
"presentation": {
  "echo": true,
  "reveal": "always",
  "focus": false,
  "panel": "new",
  "clear": true
}
```

表格

| 参数 | 说明 |
| --- | --- |
| echo | 终端打印完整执行命令 |
| reveal | always 自动弹出；silent 仅报错弹出；never 不弹出 |
| focus | 任务运行后是否自动聚焦终端 |
| panel | new 新建终端；shared 共用；dedicated 专属终端 |
| clear | 执行前清空终端历史日志 |

### 8. dependsOn 任务串行依赖

先执行依赖任务，再运行当前任务，常用于「清理 → 编译」流程

```
"dependsOn": ["Clean Boost"]
```

支持数组多任务，按数组顺序依次执行。

### 9. runOn 自动触发任务

可选值 `folderOpen`：打开项目文件夹自动运行该任务

```
"runOn": "folderOpen"
```

### 10. ignoreError

- `false`（默认）：命令返回错误码（编译失败），标记任务失败、中断流程
- `true`：忽略错误码，继续执行后续流程

## 三、全局内置路径变量（所有字段通用）

推荐使用变量，适配不同电脑路径，避免硬编码

表格

| 变量 | 含义 |
| --- | --- |
| `${workspaceFolder}` | 项目根目录 |
| `${workspaceFolderBasename}` | 项目文件夹名称 |
| `${file}` | 当前打开文件完整路径 |
| `${fileDirname}` | 当前文件所在文件夹 |
| `${env:XXX}` | 读取系统环境变量，例 `${env:PATH}` |
| `${cwd}` | 当前工作目录 |

## 四、完整注释示例（Boost b2 Windows MSVC）

```
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Boost Build Debug",
      "type": "shell",
      "command": ".\\b2.exe",
      "args": ["toolset=msvc", "variant=debug", "stage"],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": "$msCompile",
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "presentation": {
        "clear": true,
        "reveal": "always"
      },
      "windows": {
        "options": {
          "shell": {
            "executable": "cmd.exe",
            "args": ["/C", "C:\\Program Files (x86)\\Microsoft Visual Studio\\18\\BuildTools\\Common7\\Tools\\VsDevCmd.bat &&"]
          }
        }
      }
    },
    {
      "label": "Boost Build Release",
      "type": "shell",
      "command": ".\\b2.exe",
      "args": ["toolset=msvc", "variant=release", "stage"],
      "group": "build",
      "problemMatcher": "$msCompile",
      "options": {
        "cwd": "${workspaceFolder}"
      }
    },
    {
      "label": "Clean Boost",
      "type": "shell",
      "command": ".\\b2.exe clean",
      "options": {
        "cwd": "${workspaceFolder}"
      }
    }
  ]
}
```

## 五、高频实用场景总结

1. **自动加载 MSVC 编译环境**：配置 `windows.shell` 执行 `VsDevCmd.bat`
2. **调试前自动编译**：`launch.json` 中配置 `"preLaunchTask": "任务label"`
3. **编译错误跳转代码**：配置 `problemMatcher: "$msCompile"`
4. **先清理再编译**：添加 `dependsOn` 绑定清理任务
5. **临时追加库搜索路径**：`options.env` 追加 PATH 环境变量
6. **一键编译快捷键**：`group.isDefault: true`，使用 `Ctrl+Shift+B`