终端 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 集成，需要在 shell 初始化期间运行 VS Code shell 集成脚本。在何处以及如何执行此操作取决于您所使用的 shell 和操作系统。使用手动安装时，建议设置terminal.integrated.shellIntegration.enabled为false，但不是强制的。

提示：使用Insiders build时，请替换code为code-insiders以下内容。

巴什

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

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

鱼

⚠️目前处于实验阶段，不支持自动注入

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

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

普沃什

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

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

桀骜

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

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

git 重击

⚠️目前处于实验阶段，不支持自动注入

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

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

便携性与性能

上面推荐的安装 shell 集成的方法依赖于执行我们的 CLI 来查找 shell 集成脚本的路径。这非常棒，因为它可以跨平台工作，并且还适用code于$PATH. 目前，这会启动 Node.js 以获取路径，这可能会给 shell 启动带来一点延迟。为了减少这种情况，您可以通过提前解析路径并将其直接添加到初始化脚本中来内联上面的脚本。

# 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 集成实现的功能之一是能够获取终端内运行的命令的退出代码。使用此信息，将装饰添加到该行的左侧以指示命令是成功还是失败。这些装饰也显示在滚动条中相对较新的概述标尺中，就像在编辑器中一样。

蓝色圆圈出现在成功的命令旁边，带叉的红色圆圈出现在失败的命令旁边。 圆圈的颜色出现在滚动条中

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

单击成功的命令装饰会显示一个上下文菜单，其中包含以下项目：复制输出、将输出复制为 HTML、重新运行命令以及它是如何工作的？

命令和概览标尺装饰可以通过设置进行配置terminal.integrated.shellIntegration.decorationsEnabled。

命令导航

shell 集成检测到的命令会输入到命令导航功能（Ctrl/Cmd+Up、Ctrl/Cmd+Down）中，以提供更可靠的命令位置。此功能允许在命令之间快速导航并选择其输出。按住Shift 键也可以从当前位置选择到命令。

快速修复

VS Code 扫描命令的输出并提供快速修复，其中包含很可能是用户下一步想要执行的操作。

运行“git push --set-upstream”将显示一个灯泡，打开一个下拉菜单，其中包含在 github.com 上打开新 PR 的选项

以下是一些内置的快速修复：

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

快速修复功能还支持音频提示，以便在快速修复可用时提供额外反馈。

运行最近的命令

终端：运行最近的命令命令在“快速选择”中显示来自各种来源的历史记录，提供与 shell 的反向搜索 ( Ctrl+R ) 类似的功能。来源是当前会话的历史记录、该 shell 类型的先前会话历史记录以及公共 shell 历史文件。

“运行最近的命令”命令显示以前运行的命令的快速选择，可以像转到文件命令一样进行过滤

该命令的一些其他功能：

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

此命令的默认键绑定是Ctrl+Alt+R。然而，当辅助功能模式打开时，这些会相反；Ctrl+R运行最近的命令，Ctrl+Alt+R将 Ctrl+R 发送到 shell。

当辅助功能模式关闭时，可以使用以下键绑定翻转键绑定：

{
    "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：默认MenuComplete仅在 Windows 上
  • Alt+SpaceSetMark ：所有平台上默认为
  • Shift+EnterAddLine ：在所有平台上默认为
  • Shift+EndSelectLine ：在所有平台上默认为
  • Shift+HomeSelectBackwardsLine ：在所有平台上默认为

增强的可访问性

shell 集成向 VS Code 提供的信息用于提高终端的可访问性。例如，您可以在可访问缓冲区 ( ⌥F2 (Windows Alt+F2、Linux Shift+Alt+F2 ) ) 中导航检测到的命令，并且在命令失败时播放音频提示。

支持的转义序列

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

VS Code 自定义序列 'OSC 633 ；... 英石'

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> ST- 明确设置命令行。

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

    可选的随机数可用于验证来自 shell 集成脚本的序列，以防止命令欺骗。当nonce验证成功后，将取消使用命令之前的一些保护，以改善用户体验。

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

    一些例子：

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

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

    已知属性：

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

最终学期 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- 使用可选的退出代码标记执行已完成。

设置标记'OSC 1337；设置标记 ST'

此序列在其触发行的左侧添加一个标记，并向滚动条添加注释：

将序列写入终端时，命令左侧会出现一个灰色小圆圈，滚动条中会出现匹配的注释

这些标记与命令导航集成，默认情况下可以通过 ctrl/cmd+up 和 ctrl/cmd+down 轻松导航到它们。

常见问题

自动注入什么时候不起作用？

有几种情况会导致自动注入不起作用，以下是一些常见情况：

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

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

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

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

造成这种情况的可能原因是您的系统安装了VS Code 能够识别的另一个终端的 shell 集成。如果您不需要任何装饰，可以使用以下设置隐藏它们：

"terminal.integrated.shellIntegration.decorationsEnabled": never

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

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

Windows 使用名为 ConPTY 的模拟伪终端 (pty) 后端。它的工作方式与常规 pty 略有不同，因为它需要保持与 Windows 控制台 API 的兼容性。其影响之一是 pty 专门处理渲染，导致识别终端缓冲区中命令的 shell 集成序列可能会被放错位置。当命令跳转时，通常是在命令运行之后，VS Code 的启发式方法已经开始改进命令装饰的位置。

11/1/2023