cpp-study/cmake/chapter-1/VS Code tasks.md

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