变量参考

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

预定义变量

支持以下预定义变量

预定义变量示例

假设有以下条件

1. 在编辑器中打开的文件位于 /home/your-username/your-project/folder/file.ext；
2. 目录 /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
• ${fileExtname}: .ext
• ${fileDirname}: /home/your-username/your-project/folder
• ${fileDirnameBasename}: folder
• ${lineNumber}: 光标所在行号
• ${columnNumber}: 光标所在列号
• ${selectedText}: 在代码编辑器中选中的文本
• ${execPath}: Code.exe 的位置
• ${pathSeparator}: macOS 或 Linux 上为 /，Windows 上为 \

平台与工作区注意事项

平台特定行为

某些预定义变量在不同操作系统上的解析方式可能不同

• 在 Windows 上，文件路径使用反斜杠 (\)。在 tasks.json 或 launch.json 等 JSON 文件中编写路径时，请确保反斜杠已正确转义（例如："${workspaceFolder}\\subdir"）。
• 在 macOS 和 Linux 上，文件路径使用正斜杠 (/)。

建议使用 ${pathSeparator} 或 ${/} 以确保配置在不同平台间的可移植性。

按工作区文件夹划分的作用域变量

通过在变量后附加根文件夹名称（用冒号分隔），可以访问工作区的同级根文件夹。如果没有根文件夹名称，该变量的作用域仅限于使用它的文件夹。

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

环境变量

您可以使用 ${env:Name} 语法引用环境变量。例如，${env:USERNAME} 引用 USERNAME 环境变量。

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

配置变量

要引用 VS Code 设置（configurations），请使用 ${config:Name} 语法。例如，${config:editor.fontSize} 引用 editor.fontSize 设置。

命令变量

您可以使用 ${command:commandID} 语法将任何 VS Code 命令作为变量使用。

命令变量会被替换为命令求值后的（字符串）结果。命令的实现范围可以从不带 UI 的简单计算，到基于 VS Code 扩展 API 提供的 UI 功能的复杂逻辑。如果命令返回的不是字符串，则变量替换将无法完成。命令变量必须返回字符串。

此功能的一个示例是 VS Code 的 Node.js 调试器扩展，它提供了一个交互式命令 extension.pickNodeProcess，用于从所有正在运行的 Node.js 进程列表中选择单个进程。该命令返回所选进程的 ID。这使得在通过进程 ID 附加 (Attach by Process 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：如果用户没有输入其他内容，将使用的默认值。它必须是选项值之一。

选项可以是字符串值，也可以是同时包含 label（标签）和 value（值）的对象。下拉菜单将显示 label: value。

command:

• command：在变量插值时运行命令。
• args：可选的参数包，传递给命令的实现。

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

{
  "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"
    }
  ]
}

运行示例

以下示例展示了如何在调试配置中使用 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"
      }
    }
  ]
}

命令输入也可以与任务配合使用。在此示例中，使用了内置的“终止任务 (Terminate Task)”命令。它可以接受一个参数来终止所有任务。

{
  "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 在 VS Code 中打开 在 VS Code Insiders 中打开 ）拥有它们自己的变量。

  "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}"
    }
  ]
}

相关资源

• 调试
• 任务