终端壳整合

Visual Studio Code 能够与常见的 shell 集成，使终端能够更好地理解 shell 内部实际发生的事情。这些额外信息使得一些实用功能得以实现，如工作目录检测和命令检测、装饰和导航。

支撑壳体：

Linux/macOS：bash、fish、pwsh、zsh
Windows：Git Bash，呸

安装

自动脚本注入

默认情况下，shell集成脚本应在支持的VS Code启动的shell上自动激活。这是通过在 shell 会话启动时注入参数和/或环境变量来实现的。通过设置可以关闭这种自动注入

到错误.

这种标准且简单的方法对于某些高级用例，比如子壳，通常无法通过常规嘘会话（不使用远程 - SSH 扩展时）或用于某些复杂的 shell 设置。推荐的启用shell集成方法是手动安装。

注意：自动注入可能无法在旧版本的壳上工作，例如旧版鱼不支持$XDG_数据_目录环境变量，这就是注入的工作原理。你可能还能手动安装让它正常工作。

手动安装

要手动安装shell集成，VS Code的shell集成脚本需要在shell初始化时运行。具体在哪里以及如何作取决于你使用的shell和作系统。使用手动安装时建议设置为

到错误，虽然不是强制的。

提示：使用内部人构建时，替换代码其中代码内部人士如下。

砰

在你的~/.bashrc档案。跑代码 ~/.bashrc在 bash 中打开该文件。

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

鱼类

在你的config.fish.跑代码 $__fish_config_dir/config.fish在 fish 中打开 VS Code 文件。

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

PWSH

将以下内容添加到您的PowerShell配置文件中。跑代码$Profile在 PWSH 中打开该文件。

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

ZSH

在你的~/.zshrc档案。跑代码 ~/.zshrc在 zsh 中打开该文件。

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

Git Bash

在你的~/.bashrc档案。跑代码 ~/.bashrc在 Git Bash 中打开 VS Code 文件。

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

便携性与性能

上述壳层集成安装是跨平台的，并且兼容任何安装类型，满足条件代码属于$PATH.然而，这种推荐方法Node.js开始获取脚本路径，导致壳启动略有延迟。为了减少这种延迟，可以提前解析路径并直接添加到初始脚本中，内联脚本。

# 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集成时，它会有一个“质量”来声明其能力。这些特性由壳体集成脚本的行为决定。

无：没有任何 shell 集成激活。
Rich：Shell集成是主动的，命令检测也在理想中发挥作用。
基础：Shell集成是激活的，但命令检测可能不支持所有功能。例如，命令执行位置被检测到，但无法检测其退出状态。

要查看shell集成质量，请将鼠标悬停终端标签。可选地，在鼠标悬停键上选择“显示详情”以查看更详细的信息。

IntelliSense

终端中的IntelliSense允许你接收文件、文件夹、命令、命令参数和选项的建议。此功能可以通过以下方式启用或禁用

环境。

终端截图显示用户输入了git checkout并收到分支名称的建议。

你打字时，会弹出一份建议列表。要手动触发建议，请使用⌃空格（Windows，Linux Ctrl+空格）快捷键。

提示

Ctrl+Space可能是作系统层面触发输入法编辑器（IME）的按键绑定。如果是这样，你可以重新绑定workbench.action.terminal.triggerSuggest通过自定义快捷键或更改作系统级快捷方式。

默认情况下，Tab 键会插入建议。导航列表后，Enter 键插入建议。你可以用

环境。

有多种设置可以配置终端 IntelliSense 的行为：

terminal.integrated.suggest.quickSuggestions
- 在VS代码中打开
- 在VS Code Insiders中开放
：根据命令行内容自动显示，而不是手动按 Ctrl+Space 显示。
terminal.integrated.suggest.suggestOnTriggerCharacters（触发字符）
- 在VS代码中打开
- 在VS Code Insiders中开放
：在“触发字符”（如或）后自动显示。-/
terminal.integrated.suggest.runOnEnter
- 在VS代码中打开
- 在VS Code Insiders中开放
：当使用Enter时（非Tab键）可选择性地执行该命令。
terminal.integrated.suggest.windowsExecutableExtensions
- 在VS代码中打开
- 在VS Code Insiders中开放
：在Windows上被视为可执行文件的扩展列表。
terminal.integrated.suggest.providers
- 在VS代码中打开
- 在VS Code Insiders中开放
：提供了禁用特定提供者的功能，例如扩展可能会贡献你不希望的补全内容。
terminal.integrated.suggest.showStatusBar
- 在VS代码中打开
- 在VS Code Insiders中开放
：显示 IntelliSense 弹窗底部的状态栏。
terminal.integrated.suggest.cdPath
- 在VS代码中打开
- 在VS Code Insiders中开放
：启用$CDPATH整合。
terminal.integrated.suggest.inlineSuggestion
- 在VS代码中打开
- 在VS Code Insiders中开放
：与Shell“幽灵文本”集成及其呈现方式。
terminal.integrated.suggest.upArrow导航历史
- 在VS代码中打开
- 在VS Code Insiders中开放
：发送向上箭头到壳体，而不是浏览完成，这在ZSH上特别有用，你可以筛选后按上键用该前缀进行历史搜索。
terminal.integrated.suggest.selectionMode
- 在VS代码中打开
- 在VS Code Insiders中开放
： Intellisense 弹窗的焦点，决定了 Enter 和 Tab 键的功能。
terminal.integrated.suggest.insertTrailingSpace（末端空间）
- 在VS代码中打开
- 在VS Code Insiders中开放
：插入后方空格，接受后重新触发补全。

全局完成缓存

为了提升性能，VS Code 会积极缓存特定 shell 的全局缓存。当你对shell启动逻辑做添加命令的更改时，手动用终端命令刷新缓存：清除建议缓存全局（terminal.integrated.suggest.clearCachedGlobals如果它们没有被自动接收的话。

指挥勋章与概览尺

shell集成的一个功能是能够在终端内执行命令的退出代码。利用这些信息，在队列左侧添加装饰，以表示指挥成功或失败。这些装饰也会出现在滚动条中相对较新的概览尺度中，就像编辑器中一样。

成功指令旁显示蓝色圆圈，失败指令旁显示带叉的红色圆圈。圆圈的颜色显示在滚动条中

装饰可以与之交互，以获得一些上下文作，比如重启命令：

命令和概览尺的装饰可以配置为

环境。

shell集成检测到的命令会输入命令导航功能（Ctrl/Cmd+Up，Ctrl/Cmd+Down），以获得更可靠的命令位置。此功能允许快速导航命令和输出选择。要从当前位置选择命令，也可以按住Shift，按Shift+Ctrl/Cmd+Down和Shift+Ctrl/Cmd+Down。

指挥指南

指令指南是一个条，悬停时会显示在命令及其输出旁边。这有助于更快识别命令，同时也验证了shell集成是否正常。

终端截图，左侧高亮命令指南竖栏，指示命令边界。

你可以使用颜色主题自定义命令指南的颜色。要切换命令指南，请配置

环境。

粘性卷轴

粘贴滚动功能会“粘贴”显示在终端顶部的命令，方便看到该输出属于哪个命令。点击粘贴滚动组件会滚动到终端缓冲区中该命令的位置。

粘贴滚动会显示终端视口顶部的命令

这可以通过以下方式实现

环境。

快速解决方法

VS Code 扫描命令输出，并呈现快速修复，这些动作很可能是用户下一步想做的。

运行“git push --set-upstream”会弹出一个灯泡，打开一个下拉菜单，并有打开新PR的选项 github.com

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

当检测到某个端口已经被监听时，建议终止进程并重新执行之前的命令。
当Git 推送由于上游未设置而失败，建议用上游设置推送。
当git子命令失败，出现类似命令错误，建议使用类似命令。
当Git 推送结果是建议创建GitHub PR，建议打开链接。
当概述或CMD-未找到PowerShell 反馈提供者触发器，建议每个建议。

快速修复功能还支持无障碍信号，以便在快速修复可用时提供额外反馈。

运行最近指挥

终端：运行最近命令命令通过快速选择显示来自多个来源的历史，提供类似于shell反向搜索（Ctrl+R）的功能。这些源包括当前会话的历史、该shell类型的前一次会话历史以及公共shell历史文件。

“运行最近命令”命令显示了可以筛选的已运行命令的快速选择，类似于“去文件”命令

命令的其他功能包括：

默认情况下，搜索模式为“连续搜索”，意味着搜索词必须完全匹配。搜索输入右侧的按钮可以切换到模糊搜索。
在当前会话部分，快速选择右侧有一个剪贴板图标，可以在编辑器中打开命令输出。
快速选择右侧的钉置动作可以将命令钉在列表顶部。
Alt键可以按住，将文本写入终端，而无需运行文本。
上一会话部分存储的历史量由以下条件决定
terminal.integrated.shellIntegration.history
- 在VS代码中打开
- 在VS Code Insiders中开放
环境。

该命令的默认快捷键是 Ctrl+Alt+R。然而，当无障碍模式开启时，这些模式会反过来;Ctrl+R 执行最近的命令，Ctrl+Alt+R 发送 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壳当前的工作目录是什么。在Windows上，如果不尝试通过正则表达式检测提示，是无法获取这些信息的，而且在macOS和Linux上需要轮询，这对性能并不好。

这其中一个最大的特点是增强了终端中链接的解析。取一个链接package.json例如，当链接被激活且关闭 shell 集成时，会打开一个搜索快速选择，内容如下package.json如果存在多个，则作为滤波器package.json工作区中的文件。然而，当启用shell集成时，它会打开package.json文件直接存放在当前文件夹中，因为当前位置已知。这允许输出LS例如，如何可靠地打开正确的文件。

当前工作目录也用于终端标签页、运行最近命令快速选择以及“terminal.integrated.splitCwd”：“继承”特色。

扩展PowerShell键盘快捷键

Windows 的控制台 API 允许比 Linux/macOS 终端更多的快捷键，因为 VS Code 的终端模拟了后者，即使在 Windows 上，也有一些 PowerShell 键盘快捷键由于缺乏 VT 编码，无法用标准方式实现，比如 Ctrl+Space。Shell 集成允许 VS Code 附加自定义的键盘快捷方式，发送特殊序列到 PowerShell，然后在 shell 集成脚本中处理并转发给相应的按键处理器。

当启用shell集成时，以下键盘快捷键应能在PowerShell中正常工作：

Ctrl+空格：默认为菜单完整仅限Windows平台
Alt+Space：默认为SetMark所有平台
Shift+Enter：默认为加线所有平台
Shift+End：默认为SelectLine所有平台
Shift+Home：默认为选择回溯线所有平台

提升无障碍性

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程序是VScode在写之前。

OSC 633;A ST：标记提示开始。
OSC 633;B ST：标记提示结束。
OSC 633;C ST：执行前标记。
OSC 633;D [;<出口代码>] ST：标记执行并以可选退出码结束。
OSC 633; E ; <命令行> [; <nonce>] ST：明确设置命令行并设置可选的 nonce。

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

可选的 nonce 可用于验证序列是否来自 shell 集成脚本，以防止命令欺骗。当 nonce 成功验证后，使用命令前的一些保护措施将被移除，以提升用户体验。

命令行可以通过以下方式逃逸 ASCII 字符\xAB格式，其中 AB 是字符码的十六进制表示（大小写不区分），并用 S 转义出字符。这是避免分号的必要条件（\\\0x3b）以及字符0x20及以下，这对于换行和分号尤为重要。

举几个例子：
```
"\"  -> "\\"
"\n" -> "\x0a"
";"  -> "\x3b"
```
OSC 633;P ;<Property>=<Value> ST：在终端上设置属性，只处理已知属性。

已知特性：
- Cwd：向终端报告当前工作目录。
- IsWindows：表示终端是否使用Windows后端，如winpty还是conpty。这可用于支持额外的启发式，因为壳体积分序列的位置并不保证正确。有效值为确实如此以及错误.
- HasRichCommandDetection表示终端是否具备丰富的指令检测能力。该属性设为确实如此当shell集成脚本理想地按照VS Code的期望工作时，具体来说，序列应当出现在预期的位置A、B、E、C、D.

最终项壳体集成

VS Code 支持 Final Term 的 shell 集成序列，使非 VS Code 的 shell 集成脚本能够在 VS Code 中工作。这导致体验有所下降，因为它支持的功能不如OSC 633.以下是支持的具体序列：

OSC 133;一个ST：标记提示开始。
OSC 133;B街：标记提示结束。
OSC 133;C ST：执行前标记。
OSC 133;D [; <出口码>] ST：标记执行并以可选退出码结束。

iTerm2 壳体集成

支持iTerm2开创的以下序列：

OSC 1337;CurrentDir=<Cwd> ST：设置终端当前的工作目录，类似于OSC 633;P ;Cwd=<Cwd> ST.
OSC 1337;SetMark ST：在触发行左侧添加标记，并在滚动条上添加注释：

这些标记与命令导航集成，便于通过⌘↑（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 插件可能会通过取消设置，明确禁用 VS Code 的 shell 集成$VSCODE_SHELL_集成当它们初始化时。

为什么指挥装饰显示该功能被禁用时会显示？

很可能原因是你的系统安装了VS Code能理解的另一个终端的shell集成。如果你不想用装饰品，可以用以下设置隐藏它们：

"terminal.integrated.shellIntegration.decorationsEnabled": never

或者，你可以从shell的rc/startup脚本中移除shell集成脚本，但你会失去命令导航等命令感知功能。

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

Windows 使用一个名为 ConPTY 的模拟伪终端（pty）后端。它的工作方式和普通 Pty 有些不同，因为它需要保持与 Windows 控制台 API 的兼容性。其中一个影响是 pty handle 的渲染方式特别导致终端缓冲区中识别命令的 shell 集成序列可能被误置。当命令跳跃时，通常是在命令运行后，VS Code 的启发式系统已经启动，改善了指挥装饰的位置。