在 VS Code 中尝试 ！

通过任务与外部工具集成

存在许多工具可以自动执行诸如代码检查、构建、打包、测试或部署软件系统等任务。例如，TypeScript 编译器，ESLint 和 TSLint 等代码检查工具，以及 Make、Ant、Gulp、Jake、Rake 和 MSBuild 等构建系统。

VS Code can talk to a variety of external tools

这些工具大多从命令行运行，自动化软件开发内部循环（编辑、编译、测试和调试）之内和之外的工作。鉴于它们在开发生命周期中的重要性，能够在 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 Build Task

第一个条目执行 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 示例，那么从全局菜单执行 运行任务 会显示以下列表

Tasks ESLint starter

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

Tasks ESLint Problem Matcher Selection

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

Tasks ESLint Problem

此外，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 扩展检测到的任务示例。

Gulp task auto-detection

提示：您可以通过 快速打开 (⌘P (Windows, Linux Ctrl+P)) 运行任务，方法是键入 'task'、Space 和命令名称。在本例中是 '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 文件 条目。这将打开以下选择器

Configure Task Runner

注意： 如果您没有看到任务运行器模板列表，则您的文件夹中可能已经存在一个 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：定义任务输出在用户界面中的处理方式。在此示例中，显示输出的集成终端始终会 always 显示，并且每次任务运行时都会创建一个 new 新终端。
  • options：覆盖 cwd（当前工作目录）、env（环境变量）或 shell（默认 shell）的默认值。选项可以按任务设置，也可以全局或按平台设置。在此处配置的环境变量只能在任务脚本或进程中引用，如果它们是参数、命令或其他任务属性的一部分，则不会被解析。
  • runOptions：定义任务何时以及如何运行。
  • hide：在运行任务快速选择中隐藏任务，这对于复合任务中无法独立运行的元素很有用。

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

tasks.json IntelliSense

您还可以查阅 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) 来概览有效属性。

Tasks IntelliSense

除了全局菜单栏，还可以使用 命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 访问任务命令。您可以按“task”进行筛选，查看各种与任务相关的命令。

Tasks in Command Palette

复合任务

您还可以使用 dependsOn 属性将简单的任务组合成复合任务。例如，如果您有一个包含 client 和 server 文件夹的工作区，并且两者都包含一个构建脚本，您可以创建一个任务，在不同的终端中启动这两个构建脚本。如果在 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" 的任何后台/监视任务必须有一个问题匹配器来跟踪它们何时“完成”。以下任务将依次运行 task Two、task Three，然后运行 task 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 任务的文件夹时，系统会询问您是否允许在该文件夹中自动运行任务。您稍后可以使用 管理自动任务 命令并在 允许自动任务 和 禁止自动任务 之间进行选择来更改您的决定。
  • instanceLimit - 允许同时运行的任务实例数。默认值为 1。

自定义自动检测的任务

如上所述，您可以在 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...
});

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

Configure Task

按下齿轮图标。这将创建以下 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 Watch：$tsc-watch 匹配 tsc 编译器在监视模式下报告的问题。
  • JSHint：$jshint 假定文件名以绝对路径报告。
  • JSHint Stylish：$jshint-stylish 假定文件名以绝对路径报告。
  • ESLint Compact：$eslint-compact 假定输出中的文件名是相对于打开的文件夹的。
  • ESLint Stylish：$eslint-stylish 假定输出中的文件名是相对于打开的文件夹的。
  • Go：$go 匹配 go 编译器报告的问题。假定文件名是相对于打开的文件夹的。
  • CSharp and VB Compiler：$mscompile 假定文件名以绝对路径报告。
  • Lessc compiler：$lessc 假定文件名以绝对路径报告。
  • Node Sass compiler：$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}"]
}

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

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

Inputs Example

有关 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 的配置文件来更改您使用的 Shell 的编码。

如果您只需要针对特定任务进行调整，则将更改编码所需的 OS 特定命令添加到任务命令行。以下示例适用于默认代码页为 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. 使用 Build 任务手动转译
  2. 使用文件监视器自动化编译步骤

定义问题匹配器

VS Code 内置了一些最常见的 问题匹配器 ('in-the-box')。但是，市面上有许多编译器和 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) 以获取 问题 列表，您将得到以下输出

GCC Problem Matcher

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

模式中还可以使用一些其他属性。这些属性是

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

您还可以定义一个仅捕获文件的问题匹配器。为此，请定义一个 pattern，其中可选的 kind 属性设置为 file。在这种情况下，无需提供 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)

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

为此，请为 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 编译器为例。当编译器以 watch 模式启动时，它会向控制台打印以下附加信息

> 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，以便任务在后台持续运行。

一个完整的手工编写的、用于 tsc 在 watch 模式下运行的任务的 tasks.json 文件如下所示

{
  "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 Schema - 您可以查看完整的 tasks.json 模式和描述。
  • 基本编辑 - 了解功能强大的 VS Code 编辑器。
  • 代码导航 - 快速浏览源代码。
  • 语言支持 - 了解我们支持的编程语言，包括 VS Code 内置的以及通过社区扩展提供的。
  • 调试 - 在 VS Code 编辑器中直接调试源代码。

常见问题

任务可以使用与集成终端指定的 Shell 不同的 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. 确保您的命令位于您的 PATH 中，并且不需要启动脚本才能添加到 PATH 中。这是解决此问题的最彻底方法，也是推荐的解决方案。
  2. 您可以为您的任务进行一次性修复，使其以登录或交互方式运行。不建议这样做，因为它可能产生其他后果。但是，对于单个任务来说，它也可能是一个快速简单的修复方法。下面是一个使用 bash 作为 Shell 执行此操作的任务示例
{
  "type": "npm",
  "script": "watch",
  "options": {
    "shell": {
      "args": ["-c", "-l"]
    }
  }
}

上面的 npm 任务将使用命令 (-c) 运行 bash，就像任务系统默认所做的一样。然而，此任务也以登录 Shell (-l) 方式运行 bash。

05/08/2025