通过任务与外部工具集成

许多工具可以用于自动化任务，例如代码风格检查、构建、打包、测试或部署软件系统。例如，TypeScript 编译器、代码风格检查器（如 ESLint 和 TSLint）以及构建系统（如 Make、Ant、Gulp、Jake、Rake 和 MSBuild）。

这些工具通常在命令行中运行，并在软件开发循环（编辑、编译、测试和调试）的内部和外部自动化任务。鉴于它们在开发生命周期中的重要性，能够在 VS Code 中运行工具并分析其结果非常有用。VS Code 中的任务可以配置为运行脚本并启动进程，以便许多现有工具可以在 VS Code 中使用，而无需输入命令行或编写新代码。工作区或特定于文件夹的任务是通过工作区 .vscode 文件夹中的 tasks.json 文件进行配置的。

扩展还可以使用 任务提供程序 贡献任务，这些贡献的任务可以添加在 tasks.json 文件中定义的工作区特定配置。

注意：任务支持仅在处理工作区文件夹时可用。在编辑单个文件时不可用。

TypeScript Hello World

让我们从一个简单的“Hello World”TypeScript 程序开始，我们要将其编译为 JavaScript。

创建一个名为“mytask”的空文件夹，生成一个 tsconfig.json 文件，然后从该文件夹启动 VS Code。

mkdir mytask
cd mytask
tsc --init
code .

现在创建一个名为 HelloWorld.ts 的文件，其内容如下

function sayHello(name: string): void {
  console.log(`Hello ${name}!`);
}

sayHello('Dave');

按 ⇧⌘B（Windows、Linux Ctrl+Shift+B） 或从全局 终端 菜单运行 运行构建任务 将显示以下选择器

第一个条目执行 TypeScript 编译器并将 TypeScript 文件转换为 JavaScript 文件。编译器完成后，应该会有一个 HelloWorld.js 文件。第二个条目以监视模式启动 TypeScript 编译器。每次保存 HelloWorld.ts 文件时，都会重新生成 HelloWorld.js 文件。

您还可以将 TypeScript 构建或监视任务定义为默认构建任务，以便在触发 运行构建任务 时直接执行该任务 (⇧⌘B（Windows、Linux Ctrl+Shift+B））。为此，请从全局 终端 菜单中选择 配置默认构建任务。这将显示一个包含可用构建任务的选择器。选择 tsc: build 或 tsc: watch，VS Code 将生成一个 tasks.json 文件。下面显示的示例将 tsc: build 任务设为默认构建任务

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "typescript",
      "tsconfig": "tsconfig.json",
      "problemMatcher": ["$tsc"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

上面的 tasks.json 示例没有定义新任务。它将 VS Code 的 TypeScript 扩展提供的 tsc: build 任务标记为默认构建任务。您现在可以通过按 ⇧⌘B（Windows、Linux Ctrl+Shift+B） 来执行 TypeScript 编译器。

任务自动检测

VS Code 目前自动检测以下系统的任务：Gulp、Grunt、Jake 和 npm。我们正在与相应的扩展作者合作，为 Maven 和 C# 的 dotnet 命令添加支持。如果您使用 Node.js 作为运行时开发 JavaScript 应用程序，则通常会使用一个 package.json 文件来描述您的依赖项和要运行的脚本。如果您已克隆了 eslint-starter 示例，则从全局菜单执行 运行任务 会显示以下列表

如果您尚未这样做，请通过运行 npm install 来安装必要的 npm 模块。现在打开 server.js 文件，并在语句末尾添加一个分号（注意，ESLint 启动器假设语句没有分号），然后再次执行 运行任务。这次选择 npm: lint 任务。当提示您使用哪个问题匹配器时，选择 ESLint stylish

执行该任务会产生一个错误，如 问题 视图中所示

此外，VS Code 还创建了一个 tasks.json 文件，其内容如下

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint",
      "problemMatcher": ["$eslint-stylish"]
    }
  ]
}

这指示 VS Code 使用 ESLint stylish 格式扫描 npm lint 脚本的输出以查找问题。

对于 Gulp、Grunt 和 Jake，任务自动检测的工作方式相同。以下是针对 vscode-node-debug 扩展检测到的任务示例。

提示： 你可以通过快速打开（⌘P（Windows，Linux Ctrl+P））运行你的任务，方法是输入'task'，空格，然后是命令名称。在这种情况下，输入 'task lint'。

可以通过以下设置禁用任务自动检测

{
  "typescript.tsc.autoDetect": "off",
  "grunt.autoDetect": "off",
  "jake.autoDetect": "off",
  "gulp.autoDetect": "off",
  "npm.autoDetect": "off"
}

自定义任务

并非所有任务或脚本都可以在你的工作区中自动检测。有时需要定义你自己的自定义任务。假设你有一个脚本用于运行你的测试，以正确设置某些环境。该脚本存储在你的工作区内的脚本文件夹中，对于 Linux 和 macOS 命名为 test.sh，对于 Windows 命名为 test.cmd。从全局终端菜单运行配置任务，然后选择从模板创建 tasks.json 文件条目。这将打开以下选择器

注意： 如果你没有看到任务运行程序模板列表，你可能已经在你的文件夹中有一个 tasks.json 文件，并且它的内容将在编辑器中打开。关闭该文件，并将其删除或重命名，以便进行此示例。

我们正在努力支持更多自动检测功能，因此此列表在将来会越来越小。由于我们想要编写我们自己的自定义任务，因此从列表中选择其他。这将打开包含任务骨架的 tasks.json 文件。将内容替换为以下内容

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run tests",
      "type": "shell",
      "command": "./scripts/test.sh",
      "windows": {
        "command": ".\\scripts\\test.cmd"
      },
      "group": "test",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ]
}

任务的属性具有以下语义

• label：用户界面中使用的任务标签。
• type：任务的类型。对于自定义任务，它可以是 shell 或 process。如果指定了 shell，则该命令被解释为 shell 命令（例如：bash、cmd 或 PowerShell）。如果指定了 process，则该命令被解释为要执行的进程。
• command：要执行的实际命令。
• windows：任何 Windows 特定属性。当命令在 Windows 操作系统上执行时，将使用此属性而不是默认属性。
• group：定义任务所属的组。在本例中，它属于 test 组。属于测试组的任务可以通过从命令面板运行运行测试任务来执行。
• presentation：定义任务输出在用户界面中的处理方式。在本例中，显示输出的集成终端始终可见，并且每次运行任务时都会创建一个新的终端。
• options：覆盖 cwd（当前工作目录）、env（环境变量）或 shell（默认 shell）的默认值。可以为每个任务设置选项，也可以在全局范围内或针对每个平台设置选项。此处配置的环境变量只能在任务脚本或进程内部引用，如果它们是你的 args、command 或其他任务属性的一部分，则不会解析这些变量。
• runOptions：定义何时以及如何运行任务。
• hide：从运行任务快速选择中隐藏任务，这对于无法独立运行的复合任务的元素很有用。

你可以在你的 tasks.json 文件中使用 IntelliSense 查看完整的任务属性和值集。使用触发建议（⌃Space（Windows，Linux Ctrl+Space））调出建议，并在悬停时或使用阅读更多...('i') 悬停菜单阅读描述。

你还可以查看tasks.json 模式。

在涉及包含空格或其他特殊字符（如 $）的命令和参数时，shell 命令需要特殊处理。默认情况下，任务系统支持以下行为

• 如果提供单个命令，任务系统会将该命令按原样传递给底层 shell。如果该命令需要引用或转义才能正常工作，则该命令需要包含正确的引用或转义字符。例如，要列出名称包含空格的文件夹的目录，在 bash 中执行的命令应如下所示：ls 'folder with spaces'。

{
  "label": "dir",
  "type": "shell",
  "command": "dir 'folder with spaces'"
}

• 如果提供命令和参数，任务系统将在命令或参数包含空格时使用单引号。对于 cmd.exe，将使用双引号。以下所示的 shell 命令将在 PowerShell 中执行为 dir 'folder with spaces'。

{
  "label": "dir",
  "type": "shell",
  "command": "dir",
  "args": ["folder with spaces"]
}

• 如果你想控制参数的引用方式，该参数可以是一个字面量，指定该值和一个引用样式。以下示例对包含空格的参数使用转义而不是引用。

{
  "label": "dir",
  "type": "shell",
  "command": "dir",
  "args": [
    {
      "value": "folder with spaces",
      "quoting": "escape"
    }
  ]
}

除了转义，还支持以下值

• strong：使用 shell 的强引用机制，该机制会抑制字符串中的所有评估。在 PowerShell 以及 Linux 和 macOS 的 shell 中，将使用单引号 (')。对于 cmd.exe，将使用 "。
• weak：使用 shell 的弱引用机制，该机制仍然会评估字符串中的表达式（例如，环境变量）。在 PowerShell 以及 Linux 和 macOS 的 shell 中，将使用双引号 (")。cmd.exe 不支持弱引用，因此 VS Code 也使用 "。

如果命令本身包含空格，VS Code 默认也会对命令进行强引用。与参数一样，用户可以使用相同的字面量样式来控制命令的引用。

还有更多任务属性可用于配置你的工作流程。可以使用 IntelliSense（⌃Space（Windows，Linux Ctrl+Space））来概述有效的属性。

除了全局菜单栏之外，还可以使用命令面板（⇧⌘P（Windows，Linux Ctrl+Shift+P））访问任务命令。你可以按'task'过滤，并查看各种与任务相关的命令。

复合任务

你还可以使用 dependsOn 属性将任务组合成更简单的任务。例如，如果你有一个具有客户端和服务器文件夹的工作区，并且两者都包含一个构建脚本，你可以创建一个任务，在单独的终端中启动这两个构建脚本。如果在 dependsOn 属性中列出多个任务，则默认情况下会并行执行它们。

tasks.json 文件如下所示

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Client Build",
      "command": "gulp",
      "args": ["build"],
      "options": {
        "cwd": "${workspaceFolder}/client"
      }
    },
    {
      "label": "Server Build",
      "command": "gulp",
      "args": ["build"],
      "options": {
        "cwd": "${workspaceFolder}/server"
      }
    },
    {
      "label": "Build",
      "dependsOn": ["Client Build", "Server Build"]
    }
  ]
}

如果你指定 "dependsOrder": "sequence"，则你的任务依赖项将按照它们在 dependsOn 中列出的顺序执行。任何在 dependsOn 中使用的具有 "dependsOrder": "sequence" 的后台/监视任务必须具有一个问题匹配器来跟踪它们何时“完成”。以下任务依次运行任务 Two、任务 Three，然后是任务 One。

{
  "label": "One",
  "type": "shell",
  "command": "echo Hello ",
  "dependsOrder": "sequence",
  "dependsOn": ["Two", "Three"]
}

用户级任务

你可以创建不绑定到特定工作区或文件夹的用户级任务，方法是使用任务：打开用户任务命令。此处只能使用 shell 和 process 任务，因为其他任务类型需要工作区信息。

输出行为

有时你希望控制在运行任务时集成终端面板的行为。例如，你可能希望最大化编辑器空间，并且只有在你认为存在问题时才查看任务输出。可以使用任务的 presentation 属性来控制终端的行为。它提供以下属性

• reveal：控制是否将集成终端面板置于最前面。有效值为
  • always - 面板始终置于最前面。这是默认值。
  • never - 用户必须使用查看 > 终端命令（⌃`（Windows，Linux Ctrl+`））显式地将终端面板置于最前面。
  • silent - 只有在未扫描输出以查找错误和警告时，才会将终端面板置于最前面。
• revealProblems：控制在运行此任务时是否显示问题面板。优先于选项 reveal。默认值为 never。
  • always - 在执行此任务时始终显示问题面板。
  • onProblem - 仅在发现问题时才显示问题面板。
  • never - 在执行此任务时从不显示问题面板。
• focus：控制终端是否获得输入焦点。默认值为 false。
• echo：控制是否在终端中回显执行的命令。默认值为 true。
• showReuseMessage：控制是否显示“终端将被任务重用，按任意键关闭它”消息。
• panel：控制是否在任务运行之间共享终端实例。可能的值为
  • shared - 终端是共享的，其他任务运行的输出将添加到同一个终端。
  • dedicated - 终端专用于特定任务。如果再次执行该任务，将重用终端。但是，不同任务的输出将在不同的终端中显示。
  • new - 该任务的每次执行都将使用一个新的干净终端。
• clear：控制在运行此任务之前是否清除终端。默认值为 false。
• close：控制任务退出时是否关闭运行该任务的终端。默认值为 false。
• group：控制是否使用拆分窗格在特定终端组中执行任务。同一组（由字符串值指定）中的任务将使用拆分终端来显示，而不是使用新的终端面板。

你还可以修改自动检测任务的终端面板行为。例如，如果你想更改上述 ESLint 示例中npm: run lint的输出行为，请向其中添加 presentation 属性

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint",
      "problemMatcher": ["$eslint-stylish"],
      "presentation": {
        "reveal": "never"
      }
    }
  ]
}

你还可以将自定义任务与检测任务的配置混合使用。配置npm: run lint任务并添加自定义运行测试任务的 tasks.json 如下所示

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint",
      "problemMatcher": ["$eslint-stylish"],
      "presentation": {
        "reveal": "never"
      }
    },
    {
      "label": "Run tests",
      "type": "shell",
      "command": "./scripts/test.sh",
      "windows": {
        "command": ".\\scripts\\test.cmd"
      },
      "group": "test",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ]
}

运行行为

可以使用 runOptions 属性指定任务的运行行为

• reevaluateOnRerun：控制通过重新运行上一个任务命令执行任务时如何评估变量。默认值为 true，这意味着在重新运行任务时将重新评估变量。如果设置为 false，则将使用任务上次运行时解析的变量值。
• runOn：指定何时运行任务。
  • default - 只有通过运行任务命令执行任务时，才会运行该任务。
  • folderOpen - 当包含该任务的文件夹打开时，将运行该任务。 首次打开包含带有 folderOpen 任务的文件夹时，系统会询问您是否允许任务在该文件夹中自动运行。 您可以稍后使用 **管理自动任务** 命令更改您的决定，并在 **允许自动任务** 和 **禁止自动任务** 之间进行选择。

自定义自动检测的任务

如上所述，您可以在 tasks.json 文件中自定义自动检测到的任务。 通常这样做是为了修改显示属性或将问题匹配器附加到任务的输出以扫描错误和警告。 您可以通过按下右侧的齿轮图标直接从 **运行任务** 列表中自定义任务，将相应的任务引用插入 tasks.json 文件。 假设您有以下 Gulp 文件使用 ESLint 来检查 JavaScript 文件（该文件取自 https://github.com/adametry/gulp-eslint）

const gulp = require('gulp');
const eslint = require('gulp-eslint');

gulp.task('lint', () => {
  // ESLint ignores files with "node_modules" paths.
  // So, it's best to have gulp ignore the directory as well.
  // Also, Be sure to return the stream from the task;
  // Otherwise, the task may end before the stream has finished.
  return (
    gulp
      .src(['**/*.js', '!node_modules/**'])
      // eslint() attaches the lint output to the "eslint" property
      // of the file object so it can be used by other modules.
      .pipe(eslint())
      // eslint.format() outputs the lint results to the console.
      // Alternatively use eslint.formatEach() (see Docs).
      .pipe(eslint.format())
      // To have the process exit with an error code (1) on
      // lint error, return the stream and pipe to failAfterError last.
      .pipe(eslint.failAfterError())
  );
});

gulp.task('default', ['lint'], function() {
  // This will only run if the lint task is successful...
});

从全局 **终端** 菜单执行 **运行任务** 将显示以下选择器

按下齿轮图标。 这将创建以下 tasks.json 文件

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "type": "gulp",
      "task": "default",
      "problemMatcher": []
    }
  ]
}

通常，您现在会添加一个问题匹配器（在本例中为 $eslint-stylish）或修改显示设置。

使用问题匹配器处理任务输出

VS Code 可以使用问题匹配器处理来自任务的输出。 问题匹配器会扫描任务输出文本中已知的警告或错误字符串，并在编辑器中以及问题面板中内联报告这些字符串。 VS Code 附带了几个内置的“开箱即用”问题匹配器。

• TypeScript：$tsc 假设输出中的文件名相对于打开的文件夹。
• TypeScript 监视：$tsc-watch 匹配在监视模式下执行时从 tsc 编译器报告的问题。
• JSHint：$jshint 假设文件名以绝对路径形式报告。
• JSHint 时尚：$jshint-stylish 假设文件名以绝对路径形式报告。
• ESLint 简洁：$eslint-compact 假设输出中的文件名相对于打开的文件夹。
• ESLint 时尚：$eslint-stylish 假设输出中的文件名相对于打开的文件夹。
• Go：$go 匹配从 go 编译器报告的问题。 假设文件名相对于打开的文件夹。
• C# 和 VB 编译器：$mscompile 假设文件名以绝对路径形式报告。
• Lessc 编译器：$lessc 假设文件名以绝对路径形式报告。
• Node Sass 编译器：$node-sass 假设文件名以绝对路径形式报告。

您还可以创建自己的问题匹配器，我们将在 后面的部分 中讨论。

将键盘快捷键绑定到任务

如果您需要经常运行某个任务，可以为该任务定义一个键盘快捷键。

例如，要将 Ctrl+H 绑定到上面的 **运行测试** 任务，请将以下内容添加到您的 keybindings.json 文件中

{
  "key": "ctrl+h",
  "command": "workbench.action.tasks.runTask",
  "args": "Run tests"
}

变量替换

在创作任务配置时，使用一组预定义的常用变量（如活动文件（${file}）或工作区根文件夹（${workspaceFolder}））会很有用。 VS Code 在 tasks.json 文件中的字符串内支持变量替换，您可以在 变量参考 中查看预定义变量的完整列表。

注意：并非所有属性都接受变量替换。 特别是，只有 command、args 和 options 支持变量替换。

下面是将当前打开的文件传递给 TypeScript 编译器的自定义任务配置示例。

{
  "label": "TypeScript compile",
  "type": "shell",
  "command": "tsc ${file}",
  "problemMatcher": ["$tsc"]
}

类似地，您可以通过在名称前添加 ${config: 来引用项目的配置设置。 例如，${config:python.formatting.autopep8Path} 返回 Python 扩展设置 formatting.autopep8Path。

下面是自定义任务配置示例，它使用 python.formatting.autopep8Path 设置定义的 autopep8 可执行文件在当前文件上执行 autopep8

{
  "label": "autopep8 current file",
  "type": "process",
  "command": "${config:python.formatting.autopep8Path}",
  "args": ["--in-place", "${file}"]
}

如果您想为 tasks.json 或 launch.json 指定 Python 扩展使用的选定 Python 解释器，可以使用 ${command:python.interpreterPath} 命令。

如果简单的变量替换不够，您还可以通过向您的 tasks.json 文件中添加 inputs 部分来获取来自任务用户的输入。

有关 inputs 的更多信息，请参阅 变量参考。

特定于操作系统的属性

任务系统支持定义特定于操作系统的值（例如，要执行的命令）。 为此，请将特定于操作系统的文字放入 tasks.json 文件中，并在该文字中指定相应的属性。

以下示例使用 Node.js 可执行文件作为命令，并在 Windows 和 Linux 上以不同的方式处理

{
  "label": "Run Node",
  "type": "process",
  "windows": {
    "command": "C:\\Program Files\\nodejs\\node.exe"
  },
  "linux": {
    "command": "/usr/bin/node"
  }
}

有效的操作系统属性是 Windows 的 windows、Linux 的 linux 和 macOS 的 osx。 在特定于操作系统的范围内定义的属性将覆盖在任务或全局范围内定义的属性。

全局任务

任务属性也可以在全局范围内定义。 如果存在，它们将用于特定任务，除非它们定义了相同属性但具有不同的值。 在下面的示例中，有一个全局 presentation 属性，它定义所有任务都应在新面板中执行

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "presentation": {
    "panel": "new"
  },
  "tasks": [
    {
      "label": "TS - Compile current file",
      "type": "shell",
      "command": "tsc ${file}",
      "problemMatcher": ["$tsc"]
    }
  ]
}

提示：要访问全局范围 tasks.json 文件，请打开命令面板 (⇧⌘P (Windows、Linux Ctrl+Shift+P)) 并运行 **任务：打开用户任务** 命令。

PowerShell 中的字符转义

当默认 shell 为 PowerShell，或当任务配置为使用 PowerShell 时，您可能会看到意外的空间和引号转义。 意外转义仅发生在 cmdlet 中，因为 VS Code 不知道您的命令是否包含 cmdlet。 下面的示例 1 显示了一个您将获得无法与 PowerShell 一起使用的转义的情况。 示例 2 显示了跨平台的最佳方式来获得良好的转义。 在某些情况下，您可能无法遵循示例 2，您需要进行示例 3 中显示的手动转义。

"tasks": [
    {
        "label": "PowerShell example 1 (unexpected escaping)",
        "type": "shell",
        "command": "Get-ChildItem \"Folder With Spaces\""
    },
    {
        "label": "PowerShell example 2 (expected escaping)",
        "type": "shell",
        "command": "Get-ChildItem",
        "args": ["Folder With Spaces"]
    },
    {
        "label": "PowerShell example 3 (manual escaping)",
        "type": "shell",
        "command": "& Get-ChildItem \\\"Folder With Spaces\\\""
    }
]

更改任务输出的编码

任务经常与磁盘上的文件交互。 如果这些文件以与系统编码不同的编码存储在磁盘上，则需要让作为任务执行的命令知道要使用哪种编码。 由于这取决于操作系统和使用的 shell，因此没有通用的解决方案来控制这一点。 以下是关于如何使其正常工作的建议和示例。

如果您需要调整编码，您应该检查是否可以更改操作系统使用的默认编码，或者至少为您的 shell 调整其配置文件以更改其编码。

如果您只需要为特定任务进行调整，那么将调整编码所需的特定于操作系统的命令添加到任务命令行中。 以下示例适用于使用代码页 437 作为默认设置的 Windows。 该任务显示包含西里尔字母字符的文件的输出，因此需要代码页 866。 假设默认 shell 设置为 cmd.exe，列出文件的任务如下所示

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "label": "more",
      "type": "shell",
      "command": "chcp 866 && more russian.txt",
      "problemMatcher": []
    }
  ]
}

如果任务在 PowerShell 中执行，则命令需要类似于 chcp 866; more russian.txt。 在 Linux 和 macOS 上，可以使用 locale 命令来检查区域设置并调整必要的环境变量。

任务运行示例

为了突出任务的功能，以下是一些 VS Code 如何使用任务来集成 linter 和编译器等外部工具的示例。

将 TypeScript 转换为 JavaScript

TypeScript 主题 包含一个创建任务以将 TypeScript 转换为 JavaScript 并观察 VS Code 中的任何相关错误的示例。

将 Less 和 SCSS 转换为 CSS

CSS 主题提供了有关如何使用任务来生成 CSS 文件的示例。

1. 使用构建任务手动转换
2. 使用文件监视器自动执行编译步骤

定义问题匹配器

VS Code 附带了一些最常见的内置“开箱即用”问题匹配器。 但是，还有很多编译器和 linting 工具，它们都会生成自己风格的错误和警告，因此您可能需要创建自己的问题匹配器。

我们在 helloWorld.c 程序中，开发人员将 printf 误写为 prinft。 使用 gcc 编译它将生成以下警告

helloWorld.c:5:3: warning: implicit declaration of function ‘prinft’

我们想要生成一个可以捕获输出中的消息并在 VS Code 中显示相应问题的匹配器。 问题匹配器很大程度上依赖于 正则表达式。 以下部分假设您熟悉正则表达式。

提示：我们发现 RegEx101 Playground（它具有 ECMAScript（JavaScript）风格）是一种开发和测试正则表达式的好方法。

捕获上述警告（和错误）的匹配器如下所示

{
  // The problem is owned by the cpp language service.
  "owner": "cpp",
  // The file name for reported problems is relative to the opened folder.
  "fileLocation": ["relative", "${workspaceFolder}"],
  // The name that will be shown as the source of the problem.
  "source": "gcc",
  // The actual pattern to match problems in the output.
  "pattern": {
    // The regular expression. Example to match: helloWorld.c:5:3: warning: implicit declaration of function ‘printf’ [-Wimplicit-function-declaration]
    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
    // The first match group matches the file name which is relative.
    "file": 1,
    // The second match group matches the line on which the problem occurred.
    "line": 2,
    // The third match group matches the column at which the problem occurred.
    "column": 3,
    // The fourth match group matches the problem's severity. Can be ignored. Then all problems are captured as errors.
    "severity": 4,
    // The fifth match group matches the message.
    "message": 5
  }
}

请注意，file、line 和 message 属性是必需的。 fileLocation 指定任务输出中生成并匹配在问题中的文件路径是 absolute 还是 relative。 如果任务生成绝对路径和相对路径，则可以使用 autoDetect 文件位置。 使用 autoDetect，路径首先作为绝对路径进行测试，如果文件不存在，则路径被认为是相对的。

severity 指定如果模式不包含严重性，则使用哪种问题严重性。 severity 的可能值为 error、warning 或 info。

下面是一个完成的 tasks.json 文件，其中包含上面的代码（注释已删除），并用实际的任务详细信息包装

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "gcc",
      "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
      "problemMatcher": {
        "owner": "cpp",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "source": "gcc",
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    }
  ]
}

在 VS Code 中运行它并按下 ⇧⌘M (Windows、Linux Ctrl+Shift+M) 来获取问题列表，您将获得以下输出

注意： C/C++ 扩展 包含 GCC 的问题匹配器，因此无需定义我们自己的匹配器。

在模式内还可以使用几个其他属性。 它们是

• location - 如果问题位置是行或行、列或开始行、开始列、结束行、结束列，则可以使用我们的通用位置匹配组。
• endLine - 问题结束行的匹配组索引。 如果编译器没有提供结束行值，可以省略。
• endColumn - 问题结束列的匹配组索引。 如果编译器没有提供结束列值，可以省略。
• code - 问题代码的匹配组索引。 如果编译器没有提供代码值，可以省略。

您还可以定义一个仅捕获文件的匹配器。 为此，请定义一个带有可选 kind 属性（设置为 file）的 pattern。 在这种情况下，无需提供 line 或 location 属性。

注意：如果 kind 属性设置为 file，则功能模式至少要为 file 和 message 提供一个匹配组。 如果没有提供 kind 属性或 kind 属性设置为 location，则函数模式还必须提供 line 或 location 属性。

注意： 问题匹配器只解析来自给定命令的输出。如果你想解析写入到单独文件（例如日志文件）的输出，请在命令执行完毕之前让它打印出单独文件中的行。

定义多行问题匹配器

一些工具会将源文件中发现的问题分散到多行，尤其是在使用样式化报告程序时。一个例子是 ESLint；在样式化模式下它会生成类似这样的输出

test.js
  1:0   error  Missing "use strict" statement                 strict
✖ 1 problems (1 errors, 0 warnings)

我们的问题匹配器是基于行的，所以我们需要用不同的正则表达式来捕获文件名 (test.js) 和实际问题位置和消息 (1:0 error Missing "use strict" statement)。

为了做到这一点，对 pattern 属性使用一个问题模式数组。这样你就可以为你想匹配的每一行定义一个模式。

以下问题模式匹配来自 ESLint 的样式化模式输出 - 但仍然存在一个小问题，我们需要在下一步解决。下面的代码有一个第一个正则表达式来捕获文件名，第二个正则表达式来捕获行、列、严重性、消息和错误代码

{
  "owner": "javascript",
  "fileLocation": ["relative", "${workspaceFolder}"],
  "pattern": [
    {
      "regexp": "^([^\\s].*)$",
      "file": 1
    },
    {
      "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$",
      "line": 1,
      "column": 2,
      "severity": 3,
      "message": 4,
      "code": 5
    }
  ]
}

然而，如果一个资源上存在多个问题，这个模式将无法工作。例如，想象一下来自 ESLint 的以下输出

test.js
  1:0   error  Missing "use strict" statement                 strict
  1:9   error  foo is defined but never used                  no-unused-vars
  2:5   error  x is defined but never used                    no-unused-vars
  2:11  error  Missing semicolon                              semi
  3:1   error  "bar" is not defined                           no-undef
  4:1   error  Newline required at end of file but not found  eol-last
✖ 6 problems (6 errors, 0 warnings)

模式的第一个正则表达式将匹配 "test.js"，第二个匹配 "1:0 error ..."。下一行 "1:9 error ..." 被处理，但没有被第一个正则表达式匹配，所以没有捕获到任何问题。

为了使它工作，多行模式的最后一个正则表达式可以指定 loop 属性。如果设置为 true，它会指示任务系统将多行匹配器的最后一个模式应用于输出中的行，只要正则表达式匹配即可。

第一个模式捕获的信息（在本例中匹配 test.js）将与匹配 loop 模式的所有后续行组合，以创建多个问题。在这个例子中，将创建六个问题。

这是一个问题匹配器，可以完全捕获 ESLint 样式化问题

{
  "owner": "javascript",
  "fileLocation": ["relative", "${workspaceFolder}"],
  "pattern": [
    {
      "regexp": "^([^\\s].*)$",
      "file": 1
    },
    {
      "regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$",
      "line": 1,
      "column": 2,
      "severity": 3,
      "message": 4,
      "code": 5,
      "loop": true
    }
  ]
}

注意：如果你在同一个资源上有多个问题，它们位于相同的行和列，那么只显示一个问题。这适用于所有问题匹配器，而不仅仅是多行问题匹配器。

修改现有问题匹配器

如果现有问题匹配器与你需要的很接近，你可以在 tasks.json 任务中修改它。例如，$tsc-watch 问题匹配器只适用于已关闭的文档。如果你想让它适用于所有文档，你可以修改它

{
  "type": "npm",
  "script": "watch",
  "problemMatcher": {
    "base": "$tsc-watch",
    "applyTo": "allDocuments"
  },
  "isBackground": true
}

其他可修改的问题匹配器属性包括 background、fileLocation、owner、pattern、severity 和 source。

后台/监控任务

一些工具支持在后台运行，同时监视文件系统的变化，然后在磁盘上的文件发生变化时触发一个操作。对于 Gulp，这样的功能是通过 npm 模块 gulp-watch 提供的。TypeScript 编译器 tsc 通过 --watch 命令行选项内置了对它的支持。

为了提供反馈，表明后台任务在 VS Code 中处于活动状态并生成问题结果，问题匹配器必须使用额外信息来检测这些 state 变化。让我们以 tsc 编译器为例。当编译器在监视模式下启动时，它会将以下附加信息打印到控制台

> tsc --watch
12:30:36 PM - Compilation complete. Watching for file changes.

当磁盘上包含问题的文件发生变化时，会显示以下输出

12:32:35 PM - File change detected. Starting incremental compilation...
src/messages.ts(276,9): error TS2304: Cannot find name 'candidate'.
12:32:35 PM - Compilation complete. Watching for file changes.

查看输出显示以下模式

• 当 File change detected. Starting incremental compilation... 打印到控制台时，编译器运行。
• 当 Compilation complete. Watching for file changes. 打印到控制台时，编译器停止运行。
• 在这两个字符串之间，会报告问题。
• 编译器在初始启动时也会运行一次（不打印 File change detected. Starting incremental compilation... 到控制台）。

为了捕获这些信息，问题匹配器可以提供一个 background 属性。

对于 tsc 编译器，一个合适的 background 属性如下所示

"background": {
    "activeOnStart": true,
    "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.",
    "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\."
}

除了问题匹配器上的 background 属性之外，任务本身也必须标记为 isBackground，以便任务在后台持续运行。

一个完整的 tasks.json 手动创建，用于在监视模式下运行的 tsc 任务，如下所示

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "watch",
      "command": "tsc",
      "args": ["--watch"],
      "isBackground": true,
      "problemMatcher": {
        "owner": "typescript",
        "fileLocation": "relative",
        "pattern": {
          "regexp": "^([^\\s].*)\\((\\d+|\\d+,\\d+|\\d+,\\d+,\\d+,\\d+)\\):\\s+(error|warning|info)\\s+(TS\\d+)\\s*:\\s*(.*)$",
          "file": 1,
          "location": 2,
          "severity": 3,
          "code": 4,
          "message": 5
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - File change detected\\. Starting incremental compilation\\.\\.\\.",
          "endsPattern": "^\\s*\\d{1,2}:\\d{1,2}:\\d{1,2}(?: AM| PM)? - Compilation complete\\. Watching for file changes\\."
        }
      }
    }
  ]
}

后续步骤

这些是关于任务的 - 让我们继续...

• tasks.json 架构 - 你可以查看完整的 tasks.json 架构和描述。
• 基本编辑 - 了解强大的 VS Code 编辑器。
• 代码导航 - 在源代码中快速移动。
• 语言支持 - 了解我们支持的编程语言，包括随 VS Code 一起提供的语言和社区扩展。
• 调试 - 直接在 VS Code 编辑器中调试你的源代码。

常见问题

任务可以使用与集成终端指定的不同的 Shell 吗？

是的。你可以使用 "terminal.integrated.automationProfile.*" 设置来设置将用于 VS Code 中所有自动化的 Shell，包括任务。

    "terminal.integrated.automationProfile.windows": {
        "path": "cmd.exe"
    }

或者，你可以使用 options.shell 属性覆盖任务的 Shell。你可以在每个任务、全局或每个平台上设置它。例如，要在 Windows 上使用 cmd.exe，你的 tasks.json 将包括

{
    "version": "2.0.0",
    "windows": {
        "options": {
            "shell": {
                "executable": "cmd.exe",
                "args": [
                    "/d", "/c"
                ]
            }
        }
    },
    ...

后台任务可以用作 launch.json 中的 prelaunchTask 吗？

是的。由于后台任务会一直运行到被杀死，所以后台任务本身没有信号表明它已“完成”。要将后台任务用作 prelaunchTask，你必须为后台任务添加一个合适的后台 problemMatcher，以便任务系统和调试系统能够知道任务“完成”。

你的任务可能是

{
  "type": "npm",
  "script": "watch",
  "problemMatcher": "$tsc-watch",
  "isBackground": true
}

注意： $tsc-watch 是一个后台问题匹配器，这是后台任务所必需的。

然后你可以在 launch.json 文件中将任务用作 prelaunchTask

{
  "name": "Launch Extension",
  "type": "extensionHost",
  "request": "launch",
  "runtimeExecutable": "${execPath}",
  "args": ["--extensionDevelopmentPath=${workspaceRoot}"],
  "stopOnEntry": false,
  "sourceMaps": true,
  "outFiles": ["${workspaceRoot}/out/src/**/*.js"],
  "preLaunchTask": "npm: watch"
}

有关后台任务的更多信息，请访问 后台/监视任务。

为什么在运行任务时我会收到 "command not found" 的提示？

当尝试运行的任务命令未被你的终端识别为可运行命令时，就会出现 "command not found" 消息。大多数情况下，这是因为命令是在 Shell 的启动脚本中配置的。任务作为非登录和非交互式运行，这意味着 Shell 的启动脚本不会运行。特别是 nvm 众所周知会将启动脚本用作其配置的一部分。

有几种方法可以解决这个问题

1. 确保你的命令在你的路径上，并且不需要启动脚本将其添加到你的路径。这是解决问题的最彻底方法，也是推荐的解决方案。
2. 你可以对你的任务进行一次性修复，以便以登录或交互式方式运行它。不推荐这样做，因为它会产生其他后果。但是，这也可以是对单个任务进行快速简便的修复。以下是一个使用 bash 作为 Shell 的示例任务

{
  "type": "npm",
  "script": "watch",
  "options": {
    "shell": {
      "args": ["-c", "-l"]
    }
  }
}

上面的 npm 任务将运行带有命令 (-c) 的 bash，就像任务系统默认情况下所做的那样。但是，此任务还以登录 Shell (-l) 的方式运行 bash。