284 lines
6.7 KiB
Markdown
284 lines
6.7 KiB
Markdown
# 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` |