变量参考

Visual Studio Code 支持在调试和任务配置文件以及某些选定设置中进行变量替换。变量替换使用 **${variableName}** 语法支持在 launch.json 和 tasks.json 文件中某些键值字符串内。

预定义变量

支持以下预定义变量

**${userHome}** - 用户主文件夹的路径
**${workspaceFolder}** - 在 VS Code 中打开的文件夹的路径
**${workspaceFolderBasename}** - 在 VS Code 中打开的文件夹的名称，不包含任何斜杠 (/)
**${file}** - 当前打开的文件
**${fileWorkspaceFolder}** - 当前打开的文件的工作区文件夹
**${relativeFile}** - 相对于 workspaceFolder 的当前打开的文件
**${relativeFileDirname}** - 相对于 workspaceFolder 的当前打开文件的 dirname
**${fileBasename}** - 当前打开文件的基名
**${fileBasenameNoExtension}** - 当前打开文件的基名，不包含文件扩展名
**${fileExtname}** - 当前打开文件的扩展名
**${fileDirname}** - 当前打开文件的文件夹路径
**${fileDirnameBasename}** - 当前打开文件的文件夹名称
**${cwd}** - VS Code 启动时任务运行器的当前工作目录
**${lineNumber}** - 活动文件中当前选定的行号
**${selectedText}** - 活动文件中当前选定的文本
**${execPath}** - 运行 VS Code 可执行文件的路径
**${defaultBuildTask}** - 默认构建任务的名称
**${pathSeparator}** - 操作系统用来分隔文件路径中组件的字符
**${/}** - **${pathSeparator}** 的简写

预定义变量示例

假设您有以下要求

在您的编辑器中打开的文件位于 /home/your-username/your-project/folder/file.ext；
目录 /home/your-username/your-project 作为您的根工作区打开。

因此，您将为每个变量获得以下值

**${userHome}** - /home/your-username
**${workspaceFolder}** - /home/your-username/your-project
**${workspaceFolderBasename}** - your-project
**${file}** - /home/your-username/your-project/folder/file.ext
**${fileWorkspaceFolder}** - /home/your-username/your-project
**${relativeFile}** - folder/file.ext
**${relativeFileDirname}** - folder
**${fileBasename}** - file.ext
**${fileBasenameNoExtension}** - file
**${fileDirname}** - /home/your-username/your-project/folder
**${fileExtname}** - .ext
**${lineNumber}** - 光标所在的行号
**${selectedText}** - 在您的代码编辑器中选定的文本
**${execPath}** - Code.exe 的位置
**${pathSeparator}** - macOS 或 linux 上为 /，Windows 上为 \

提示：在 tasks.json 和 launch.json 的字符串值内使用 IntelliSense 以获取预定义变量的完整列表。

针对每个工作区文件夹的变量

通过将根文件夹的名称追加到变量（用冒号分隔），可以访问工作区的兄弟根文件夹。如果没有根文件夹名称，则变量的范围仅限于其使用的相同文件夹。

例如，在具有 Server 和 Client 文件夹的多根工作区中，${workspaceFolder:Client} 指的是 Client 根的路径。

环境变量

您还可以通过 **${env:Name}** 语法（例如，${env:USERNAME}）引用环境变量。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

配置变量

您可以通过 **${config:Name}** 语法（例如，${config:editor.fontSize}）引用 VS Code 设置（“配置”）。

命令变量

如果上述预定义变量不足，则可以通过 **${command:commandID}** 语法使用任何 VS Code 命令作为变量。

命令变量将被命令评估的结果（字符串）替换。命令的实现可以从没有 UI 的简单计算到基于 VS Code 扩展 API 提供的 UI 功能的某些复杂功能。如果命令返回的不是字符串，则变量替换将无法完成。命令变量**必须**返回字符串。

此功能的一个示例是在 VS Code 的 Node.js 调试器扩展中，该扩展提供了交互式命令 extension.pickNodeProcess 用于从所有正在运行的 Node.js 进程列表中选择单个进程。该命令返回所选进程的进程 ID。这使得可以在 **按进程 ID 附加** 启动配置中使用 extension.pickNodeProcess 命令，方法如下

{
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach by Process ID",
      "processId": "${command:extension.pickNodeProcess}"
    }
  ]
}

在 launch.json 配置中使用命令变量时，包含的 launch.json 配置将作为对象通过参数传递给命令。这使命令能够知道调用它们时特定 launch.json 配置的上下文和参数。

输入变量

命令变量已经很强大，但它们缺少为特定用例配置正在运行的命令的机制。例如，无法将**提示消息**或**默认值**传递给通用的“用户输入提示”。

输入变量解决了此限制，其语法为：${input:variableID}。variableID 指的是 launch.json 和 tasks.json 的 inputs 部分中的条目，其中指定了其他配置属性。不支持输入变量的嵌套。

以下示例展示了使用输入变量的tasks.json的整体结构

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "task name",
      "command": "${input:variableID}"
      // ...
    }
  ],
  "inputs": [
    {
      "id": "variableID",
      "type": "type of input variable"
      // type specific configuration attributes
    }
  ]
}

目前 VS Code 支持三种类型的输入变量

promptString: 显示一个输入框，以便从用户获取字符串。
pickString: 显示一个快速选择下拉菜单，让用户从多个选项中选择。
command: 运行任意命令。

每种类型都需要额外的配置属性

promptString:

description: 在快速输入中显示，为输入提供上下文。
default: 如果用户没有输入其他内容，将使用的默认值。
password: 设置为 true 以使用密码提示输入，不会显示输入的值。

pickString:

description: 在快速选择中显示，为输入提供上下文。
options: 用户可以选择的一组选项。
default: 如果用户没有输入其他内容，将使用的默认值。它必须是选项值之一。

一个选项可以是字符串值，也可以是包含标签和值的**对象**。下拉菜单将显示**标签：值**。

command:

command: 在变量插值时运行的命令。
args: 传递给命令实现的可选选项包。

以下是一个使用 Angular CLI 说明inputs用法的tasks.json示例

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ng g",
      "type": "shell",
      "command": "ng",
      "args": ["g", "${input:componentType}", "${input:componentName}"]
    }
  ],
  "inputs": [
    {
      "type": "pickString",
      "id": "componentType",
      "description": "What type of component do you want to create?",
      "options": [
        "component",
        "directive",
        "pipe",
        "service",
        "class",
        "guard",
        "interface",
        "enum"
      ],
      "default": "component"
    },
    {
      "type": "promptString",
      "id": "componentName",
      "description": "Name your component.",
      "default": "my-new-component"
    }
  ]
}

运行示例

Inputs Example

以下示例演示了如何在调试配置中使用类型为command的用户输入变量，该变量允许用户从特定文件夹中找到的所有测试用例列表中选择一个测试用例。假定某些扩展提供了一个extension.mochaSupport.testPicker命令，该命令可以在可配置的位置找到所有测试用例，并显示一个选择器 UI 来选择其中一个。命令输入的参数由命令本身定义。

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run specific test",
      "program": "${workspaceFolder}/${input:pickTest}"
    }
  ],
  "inputs": [
    {
      "id": "pickTest",
      "type": "command",
      "command": "extension.mochaSupport.testPicker",
      "args": {
        "testFolder": "/out/tests"
      }
    }
  ]
}

命令输入也可以与任务一起使用。在本示例中，使用了内置的终止任务命令。它可以接受一个参数来终止所有任务。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Terminate All Tasks",
      "command": "echo ${input:terminate}",
      "type": "shell",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "terminate",
      "type": "command",
      "command": "workbench.action.tasks.terminate",
      "args": "terminateAll"
    }
  ]
}

常见问题

调试配置或任务中变量替换的详细信息

调试配置或任务中的变量替换是一个两遍式过程

在第一遍中，所有变量都被评估为字符串结果。如果一个变量出现多次，它只被评估一次。
在第二遍中，所有变量都用第一遍的结果替换。

这样做的一个结果是，变量的评估（例如，在扩展中实现的基于命令的变量）无法访问调试配置或任务中的其他替换变量。它只能看到原始变量。这意味着变量不能相互依赖（这保证了隔离，并使替换不受评估顺序的影响）。

用户和工作区设置中是否支持变量替换？

预定义变量在settings.json文件中的某些设置键（如终端cwd、env、shell和shellArgs值）中受支持。一些设置（如window.title）有自己的变量

  "window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}"

请参阅设置编辑器中的注释（⌘,（Windows、Linux Ctrl+,））以了解特定设置的变量。

为什么没有记录 ${workspaceRoot}？

变量${workspaceRoot}已被弃用，取而代之的是${workspaceFolder}，以便更好地与多根工作区支持保持一致。

为什么 tasks.json 中的变量没有解析？

并非tasks.json中的所有值都支持变量替换。具体而言，只有command、args和options支持变量替换。inputs部分中的输入变量不会解析，因为不支持输入变量的嵌套。

如何知道变量的实际值？

检查变量运行时值的一种简单方法是创建一个 VS Code 任务，将变量值输出到控制台。例如，要查看${workspaceFolder}的解析值，您可以在tasks.json中创建并运行（终端 > 运行任务）以下简单的“echo”任务

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "echo",
      "type": "shell",
      "command": "echo ${workspaceFolder}"
    }
  ]
}

10/29/2024