现已推出！阅读 10 月份的新功能和修复。

终端 Shell 集成

Visual Studio Code 能够与常见的 Shell 集成，使终端能够更好地理解 Shell 内部实际发生的情况。这些附加信息使一些有用功能成为可能，例如 工作目录检测 和命令检测、装饰 以及 导航。

支持的 Shell

  • Linux/macOS：bash、fish、pwsh、zsh
  • Windows：pwsh

安装

自动脚本注入

默认情况下，Shell 集成脚本应在从 VS Code 启动的支持的 Shell 上自动激活。这是通过在 Shell 会话启动时注入参数和/或环境变量来实现的。可以通过将 terminal.integrated.shellIntegration.enabled 设置为 false 来禁用此自动注入。

这种标准的、简便的方法不适用于某些高级用例，例如子 Shell、通过常规的 ssh 会话（不使用 远程 - SSH 扩展）或某些复杂的 Shell 设置。对于这些情况，建议使用 手动安装 来启用 Shell 集成。

注意：自动注入可能无法在旧版本的 Shell 上正常工作，例如旧版本的 fish 不支持 $XDG_DATA_DIRS 环境变量，而这就是注入工作方式。你仍然可以通过手动安装来使其正常工作。

手动安装

要手动安装 Shell 集成，VS Code Shell 集成脚本需要在你的 Shell 初始化期间运行。具体操作步骤取决于你使用的 Shell 和操作系统。在使用手动安装时，建议将 terminal.integrated.shellIntegration.enabled 设置为 false，尽管这不是强制性的。

提示：使用 内部人员版本 时，请将下面的 code 替换为 code-insiders。

bash

将以下内容添加到你的 ~/.bashrc 文件中。在 bash 中运行 code ~/.bashrc 以在 VS Code 中打开该文件。

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

fish

将以下内容添加到你的 config.fish 文件中。在 fish 中运行 code $__fish_config_dir/config.fish 以在 VS Code 中打开该文件。

string match -q "$TERM_PROGRAM" "vscode"
and . (code --locate-shell-integration-path fish)

pwsh

将以下内容添加到你的 PowerShell 配置文件 中。在 pwsh 中运行 code $Profile 以在 VS Code 中打开该文件。

if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

zsh

将以下内容添加到你的 ~/.zshrc 文件中。在 bash 中运行 code ~/.zshrc 以在 VS Code 中打开该文件。

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"

Git Bash

将以下内容添加到你的 ~/.bashrc 文件中。在 Git Bash 中运行 code ~/.bashrc 以在 VS Code 中打开该文件。

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

可移植性与性能

如果 code 在 $PATH 中，上面的 Shell 集成安装是跨平台的，并且与任何安装类型兼容。但是，这种推荐的方法会启动 Node.js 来获取脚本路径，这会导致 Shell 启动时略有延迟。要减轻此延迟，请提前解析上面的脚本路径，并将其直接添加到你的 init 脚本中，从而内联该脚本。

# Output the executable's path first:
code --locate-shell-integration-path bash

# Add the result of the above to the source statement:
[[ "$TERM_PROGRAM" == "vscode" ]] && . "/path/to/shell/integration/script.sh"

命令装饰和概述标尺

Shell 集成启用的一项功能是获取在终端中运行的命令的退出代码。使用此信息，会在行的左侧添加装饰，以指示命令是成功还是失败。这些装饰也会出现在滚动条中相对较新的概述标尺上，就像在编辑器中一样。

Blue circles appear next to successful commands, red circles with crosses appear next to failed commands. The color of the circles appears in the scroll bar

可以与这些装饰进行交互，以提供一些上下文操作，例如重新运行命令。

Clicking a successful command decoration shows a context menu containing items: Copy Output, Copy Output as HTML, Rerun Command and How does this work?

可以使用 terminal.integrated.shellIntegration.decorationsEnabled 设置配置命令和概述标尺装饰。

命令导航

Shell 集成检测到的命令会输入命令导航功能 (Ctrl/Cmd+Up、Ctrl/Cmd+Down)，使其能够更可靠地定位命令。此功能允许在命令之间快速导航，并选择它们的输出。要从当前位置选择到命令，也可以按住 Shift 键，按 Shift+Ctrl/Cmd+Up 和 Shift+Ctrl/Cmd+Down。

命令指南

命令指南是一个条，当悬停在命令及其输出上时，会显示在命令旁边。这有助于更快地识别命令，也是验证 Shell 集成是否正常工作的一种方法。

Screenshot of the terminal, highlighting the command guide vertical bar on the left-hand side to indicate the boundary of a command.

可以使用颜色主题自定义命令指南的颜色。要切换命令指南，请配置 terminal.integrated.shellIntegration.showCommandGuide 设置。

粘性滚动

粘性滚动功能会将终端顶部部分显示的命令“粘住”，使您更轻松地查看该输出属于哪个命令。单击粘性滚动组件将滚动到该命令在终端缓冲区中的位置。

Sticky scroll will show the command at the top of the terminal viewport

可以通过 terminal.integrated.stickyScroll.enabled 设置启用此功能。

快速修复

VS Code 会扫描命令的输出并提供一个快速修复，其中包含一系列操作，这些操作很有可能就是用户接下来想要执行的操作。

Running 'git push --set-upstream' will present a lightbulb that opens a dropdown with an option to open a new PR on github.com

以下是一些内置的快速修复功能。

  • 当检测到某个端口已被监听时，建议终止该进程并重新运行之前的命令。
  • 当 git push 由于未设置上游而失败时，建议使用已设置上游的方式进行推送。
  • 当 git 子命令因类似的命令错误而失败时，建议使用类似的命令。
  • 当 git push 的结果是建议创建 GitHub PR 时，建议打开该链接。
  • 当 General 或 cmd-not-found PowerShell 反馈提供程序触发时，建议每个建议。

快速修复功能还支持 辅助功能信号，以便在有可用的快速修复时提供额外的反馈。

运行最近的命令

**终端：运行最近的命令** 命令会从各种来源中显示快速选择中的历史记录，提供类似于 shell 反向搜索（Ctrl+R）的功能。这些来源包括当前会话的历史记录、此 shell 类型之前的会话历史记录以及通用的 shell 历史记录文件。

The "run recent command" command shows a quick pick with previously run commands that can be filtered similar to the go to file command

该命令的其他一些功能。

  • 默认情况下，搜索模式为“连续搜索”，这意味着搜索词必须完全匹配。搜索输入框右侧的按钮允许切换到模糊搜索。
  • 在当前会话部分，快速选择框右侧有一个剪贴板图标，单击该图标将在编辑器中打开命令输出。
  • 快速选择框右侧的固定操作可以将命令固定到列表顶部。
  • 按住 Alt 键可以在不运行的情况下将文本写入终端。
  • 在之前会话部分中存储的历史记录数量由 terminal.integrated.shellIntegration.history 设置决定。

此命令的默认键盘快捷键为 Ctrl+Alt+R。但是，当启用辅助功能模式时，这些快捷键会被颠倒；Ctrl+R 会运行最近的命令，而 Ctrl+Alt+R 会向 shell 发送 Ctrl+R。

在禁用辅助功能模式的情况下，可以通过以下键盘快捷键来切换这些快捷键。

{
    "key": "ctrl+r",
    "command": "workbench.action.terminal.runRecentCommand",
    "when": "terminalFocus"
},
{
  "key": "ctrl+alt+r",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u0012"/*^R*/ },
  "when": "terminalFocus"
}

转到最近的目录

与运行最近的命令功能类似，**终端：转到最近的目录** 命令会跟踪访问过的目录，并允许快速筛选和导航（cd）到这些目录。按住 Alt 键可以在不运行的情况下将文本写入终端。

此命令的默认键盘快捷键为 ⌘G（Windows、Linux Ctrl+G），因为它与编辑器中的**转到行/列** 命令类似。Ctrl+G 可以使用 Ctrl+Alt+G 发送到 shell。

当前工作目录检测

Shell 集成会告诉 VS Code shell 的当前工作目录是什么。在没有尝试通过正则表达式检测提示的情况下，在 Windows 上无法获取此信息，并且在 macOS 和 Linux 上需要轮询，这对性能不利。

此功能启用的一项重要功能是增强了终端中链接的解析。以链接 package.json 为例，当禁用 shell 集成时激活该链接时，如果工作区中有多个 package.json 文件，将打开一个以 package.json 作为筛选器的搜索快速选择。但是，当启用 shell 集成时，它会直接打开当前文件夹中的 package.json 文件，因为已知当前位置。这使得例如 ls 的输出能够可靠地打开正确文件。

当前工作目录还用于在终端选项卡、运行最近的命令快速选择以及 "terminal.integrated.splitCwd": "inherited" 功能中显示目录。

扩展的 PowerShell 键绑定

Windows 的控制台 API 允许使用比 Linux/macOS 终端更多的键盘快捷键，由于 VS Code 的终端即使在 Windows 上也模拟后者，因此由于缺少 VT 编码（例如 Ctrl+Space），因此某些 PowerShell 键盘快捷键无法使用标准方法。Shell 集成允许 VS Code 附加一个自定义键盘快捷键，以向 PowerShell 发送一个特殊序列，然后该序列在 shell 集成脚本中处理并转发到正确的键处理程序。

以下键盘快捷键在启用 shell 集成时应在 PowerShell 中有效。

  • Ctrl+Space：仅在 Windows 上默认为 MenuComplete。
  • Alt+Space：在所有平台上默认为 SetMark。
  • Shift+Enter：在所有平台上默认为 AddLine。
  • Shift+End：在所有平台上默认为 SelectLine。
  • Shift+Home：在所有平台上默认为 SelectBackwardsLine。

PowerShell 的实验性 IntelliSense

PowerShell 的实验性 IntelliSense 在 PowerShell 中键入时会显示一个完成列表，类似于编辑器体验。在幕后，此功能由 PowerShell 会话的本机完成 API 提供支持，因此可以使用上下文感知完成，例如变量。

PowerShell IntelliSense shows completions like Get-Alias, Get-ChildItem, for example when typing Get-

您可以使用 terminal.integrated.suggest.enabled 设置启用 PowerShell 的实验性 IntelliSense。

"terminal.integrated.suggest.enabled": true

注意：此功能目前仅在 Windows 和 macOS 上可用。

Git 和 VS Code 完成。

当启用实验性 IntelliSense 时，CLI git、code 和 code-insiders 的完成默认情况下会打开。如果您的 PowerShell 配置文件已包含完成功能，您可能希望通过使用 terminal.integrated.suggest.builtinCompletions 设置来关闭这些功能。

增强的辅助功能

shell 集成提供给 VS Code 的信息用于改进 终端中的辅助功能。一些增强功能示例包括：

  • 在可访问的缓冲区中导航检测到的命令（⌥F2（Windows Alt+F2，Linux Shift+Alt+F2））。
  • 命令失败时会播放 音频提示。
  • 底层文本框同步，以便使用箭头键和退格键的行为更加正确。

支持的转义序列

VS Code 支持多种自定义转义序列。

VS Code 自定义序列“OSC 633 ; ... ST”。

VS Code 有一组自定义转义序列，旨在在 VS Code 的终端中运行时启用 shell 集成功能。这些序列由内置脚本使用，但也可由任何能够向终端发送序列的应用程序使用，例如 Julia 扩展 使用这些序列来支持 Julia REPL 中的 shell 集成。

其他终端应忽略这些序列，但除非其他终端最终更广泛地采用这些序列，否则建议在写入这些序列之前检查 $TERM_PROGRAM 是否为 vscode。

  • OSC 633 ; A ST - 标记提示开始。

  • OSC 633 ; B ST - 标记提示结束。

  • OSC 633 ; C ST - 标记预执行。

  • OSC 633 ; D [; <exitcode>] ST - 标记执行完成，并带有一个可选的退出代码。

  • OSC 633 ; E ; <commandline> [; <nonce] ST - 显式设置命令行，并带有一个可选的随机数。

    E 序列允许终端可靠地获取 shell 解释的准确命令行。如果没有指定，终端可能会回退到使用 A、B 和 C 序列获取命令，或者如果不可靠，则完全禁用检测。

    可选随机数可用于验证该序列来自 shell 集成脚本，以防止命令欺骗。当随机数成功验证时，使用命令之前的一些保护措施将被移除，以提高用户体验。

    命令行可以使用 \xAB 格式来转义 ASCII 字符，其中 AB 是字符代码的十六进制表示形式（不区分大小写），并使用 \\ 来转义 \ 字符。需要转义分号（0x3b）和字符 0x20 及以下的字符，这对换行符和分号尤其重要。

    一些示例。

    "\"  -> "\\"
"\n" -> "\x0a"
";"  -> "\x3b"

  • OSC 633 ; P ; <Property>=<Value> ST - 在终端上设置一个属性，只处理已知的属性。

    已知属性。

    • Cwd - 向终端报告当前工作目录。
    • IsWindows - 指示终端是否使用 Windows 后端，例如 winpty 或 conpty。这可以用于启用其他启发式方法，因为 shell 集成序列的位置不能保证是正确的。有效值包括 True 和 False。

Final Term shell 集成。

VS Code 支持 Final Term 的 shell 集成序列，这些序列允许非 VS Code shell 集成脚本在 VS Code 中工作。这会导致体验有所下降，因为它不支持 OSC 633 那么多功能。以下是支持的特定序列。

  • OSC 133 ; A ST - 标记提示开始。
  • OSC 133 ; B ST - 标记提示结束。
  • OSC 133 ; C ST - 标记预执行。
  • OSC 133 ; D [; <exitcode>] ST - 标记执行完成，并带有一个可选的退出代码。

iTerm2 shell 集成。

以下由 iTerm2 首创的序列受支持。

  • OSC 1337 ; CurrentDir=<Cwd> S - 设置终端的当前工作目录，类似于 OSC 633 ; P ; Cwd=<Cwd> ST。

  • OSC 1337 ; SetMark ST - 在触发它的行的左侧添加一个标记，并在滚动条中添加一个注释。

    When the sequence is written to the terminal a small grey circle will appear to the left of the command, with a matching annotation in the scroll bar

    这些标记与命令导航集成在一起，便于通过 ⌘↑（Windows、Linux Ctrl+Up） 和 ⌘↓（Windows、Linux Ctrl+Down） 进行导航。

常见问题

何时自动注入不起作用？

自动注入在几种情况下不起作用，以下是一些常见情况。

  • $PROMPT_COMMAND 格式不受支持，将其更改为指向单个函数是解决此问题的一种简单方法。例如

    prompt() {
  printf "\033]0;%s@%s:%s\007" "${USER}" "${HOSTNAME%%.*}" "${PWD/#$HOME/\~}"
}
PROMPT_COMMAND=prompt

  • 一些 shell 插件可能会在初始化时通过取消设置 $VSCODE_SHELL_INTEGRATION 来显式地禁用 VS Code 的 shell 集成。

为什么在禁用该功能时命令装饰会显示？

这很可能是因为您的系统安装了另一个终端的 shell 集成，VS Code 可以识别该 shell 集成。如果您不想看到任何装饰，可以使用以下设置将其隐藏。

"terminal.integrated.shellIntegration.decorationsEnabled": never

或者，您可以从 shell rc/启动脚本中删除 shell 集成脚本，但您将无法访问命令感知功能，例如 命令导航。

为什么命令装饰在 Windows 上会跳来跳去？

Windows 使用一个名为 ConPTY 的模拟伪终端 (pty) 后端。它的工作原理与常规 pty 略有不同，因为它需要与 Windows 控制台 API 保持兼容性。其中一个影响是，pty 以特殊方式处理渲染，因此识别终端缓冲区中命令的 shell 集成序列可能会放错位置。通常在命令运行后，命令会跳来跳去，VS Code 的启发式算法会启动以改进命令装饰的位置。

10/29/2024