终端 Shell 集成

Visual Studio Code 能够与常见的 shell 集成，使终端能够更好地理解 shell 里面正在发生的事情。这些额外的信息启用了一些有用的功能，例如工作目录检测和命令检测，装饰，和导航。

支持的 shell：

Linux/macOS: bash, fish, pwsh, zsh
Windows: Git Bash, pwsh

安装

自动脚本注入

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

至假的输入：.

这个标准、简单的方法对一些高级用例（如在子 shell 中）和通过常规方式不会有效。安全外壳协议 会话（当不使用远程 - SSH 扩展）或某些复杂的 shell 设置。推荐的启用 shell 集成的方法是手动安装。

注意：自动注入可能在旧版本的 shell 上不起作用，例如较早版本的 fish 不支持 $XDG_DATA_DIRS环境变量，这是注入是如何工作的。您仍然可以手动安装以使其正常工作。

手动安装

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

至假的，尽管不是强制性的。

提示： 当使用内部版本时，替换 代码与代码内幕在下面。

巴什

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

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

鱼

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

字符串 匹配 -q "$TERM_PROGRAM" "vscode"
和 . (code --locate-shell-integration-path fish)

pwsh

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

如果 ($env:TERM_PROGRAM 等于 "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

zsh

请将以下内容添加到你的~/.zshrc文件。运行代码 ~/.zshrc在 zsh 中打开 VS Code 文件。

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

Git 提示符

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

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

可移植性与性能

上述的 shell 集成安装是跨平台的，并且与任何安装类型兼容，如果代码在$PATH然而，这种方法会在启动 shell 时启动 Node.js 来获取脚本路径，从而导致轻微的延迟。为了减少这种延迟，请提前解析路径并直接将上述脚本嵌入到你的初始化脚本中。

# 先输出可执行文件的路径：
code --locate-shell-integration-path bash

# 将上面的结果添加到源语句：
[[ "$TERM_PROGRAM" == "vscode" ]] && . "/path/to/shell/integration/script.sh"

Shell积分质量

在使用壳集成时，它有一个“质量”与其能力相关联。这些质量由壳集成脚本的行为决定。

无：没有启用任何外壳集成。
富：外壳集成已激活，命令检测正在理想地工作。
基本：外壳集成已启用，但命令检测可能不支持所有功能。例如，检测到命令的运行位置，但不检测其退出状态。

要查看外壳集成质量，请悬停在终端标签上。可选地，选择显示详细信息以查看更多详细信息。

智能感知

在终端中启用IntelliSense可以让你收到有关文件、文件夹、命令、命令参数和选项的建议。这个功能可以通过以下方式启用或禁用

设置。

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

在你输入时，将会出现一些建议。要手动触发建议，请使用⌃Space（Windows, LinuxCtrl+Space）键盘快捷键。

小贴士

Ctrl+Space 可能是操作系统级别触发输入法编辑器（IME）的键绑定。如果是这样，您可以重新绑定 工作台.操作.终端.触发建议 命令使用自定义快捷键或更改操作系统级别的快捷键。

默认情况下，Tab插入建议。一旦你导航列表，Enter插入建议。你可以通过

设置。

有各种设置来配置终端 IntelliSense 的行为：

终端.集成.建议.快速建议
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
：根据命令行内容自动显示，而不是通过Ctrl+Space手动显示。
终端.集成.建议.在触发字符时建议
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
在“触发字符”之后自动显示，例如输入：-或输入：/输入：.
终端.集成.建议.按回车键执行
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
：可选地在回车被使用时运行命令（不是制表符）。
终端.集成.建议.Windows可执行文件扩展名
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
: Windows 上被视为可执行文件的扩展列表。
终端.集成.建议提供者
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
提供禁用特定提供者的能力，例如扩展可能会贡献你不想要的完成。
终端.集成.建议.显示状态栏
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
显示在IntelliSense弹出Windows底部的状态栏。
终端.集成.建议.目录路径
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
启用$CDPATH整合。
终端.集成.建议.内联建议
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
: 与 shell 集成 "幽灵文本" 及其呈现方式。
终端.集成.建议.上箭头导航历史记录
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
发送上箭头到 shell 而不是浏览完成，这在 zsh 中特别有用，你可以在其中过滤然后按上箭头来用该前缀进行历史搜索。
终端.集成.建议.选择模式
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
：如何聚焦Intellisense弹出Windows，这决定了回车键和Tab键的作用。
终端.集成.建议.插入尾随空格
- 在 VS Code 中打开
- 在 VS Code Insiders 中打开
插入一个尾随空格并在接受后重新触发完成。

全局完成缓存

为了提高性能，VS Code 会为特定的 shell 激进地缓存全局变量。当你更改 shell 启动逻辑并添加命令时，手动用 终端：清除建议缓存的全局变量 命令刷新缓存 (终端.集成.建议.清除缓存的全局变量) 如果它们没有被自动拾取。

命令装饰和概览标尺

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

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

这些装饰品可以进行互动，以执行一些上下文相关的操作，例如重新运行命令：

命令和概览标尺装饰可以通过

设置。

通过 shell 集成检测到的命令输入到命令导航功能 (Ctrl/Cmd+Up, Ctrl/Cmd+Down) 中，以使其命令位置更加可靠。此功能允许快速导航命令并选择其输出。要从当前位置选择到命令，您还可以按住 Shift，按下 Shift+Ctrl/Cmd+Up 和 Shift+Ctrl/Cmd+Down。

命令指南

命令指南是一条在悬停命令及其输出旁边显示的条目。这有助于更快地识别命令，并且也是验证 shell 集成是否正常工作的一种方式。

终端截图，突出显示左侧的命令指南竖线，以指示命令的边界。

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

设置。

粘性滚动

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

粘性滚动将在终端视口顶部显示命令

这可以通过启用

设置。

快速修复

VS Code 扫描命令的输出，并提供一个快速修复选项，其中包含用户可能希望执行的行动。

运行 'git push --set-upstream' 将显示一个灯泡，打开一个下拉菜单，提供在 github.com 上打开新 PR 的选项

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

当检测到端口已被监听时，建议杀死进程并重新运行之前的命令。
当git 推送由于上游未设置，失败，建议设置上游后推送。
当一个吉特子命令失败，出现类似命令错误，建议使用类似命令。
当git 推送结果是建议创建一个GitHub PR，建议打开链接。
当一个一般或命令未找到PowerShell反馈提供者触发，建议每个建议。

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

运行最近的命令

终端：运行最近的命令命令在快速选择中显示来自各个来源的历史记录，类似于 shell 的反向搜索 (Ctrl+R)。这些来源是当前会话的历史记录、此 shell 类型的以前会话历史记录以及常见的 shell 历史记录文件。

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

命令的其他功能：

默认搜索模式是“连续搜索”，这意味着搜索词必须完全匹配。搜索输入右侧的按钮可以切换到模糊搜索。
在当前会话部分，快速选择右侧有一个剪贴板图标，它将打开命令输出编辑器。
快速选择右侧的别名可以将命令固定到列表顶部。
Alt 可以按住以将文本写入终端而不运行它。
上一个会话部分中存储的历史记录数量由
终端.集成.外壳集成.历史记录
- 在 VS Code 中打开
- 在 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"
}

转到最近目录

类似于最近命令功能，终端：转到最近目录命令会跟踪已访问的目录并允许快速过滤和导航 (光盘) 给他们。Alt 可以按住以将文本写入终端而不运行它。

此命令的默认键盘快捷键是⌘G（Windows, LinuxCtrl+G），因为它在编辑器中类似于转到行/列命令。Ctrl+G 可以通过Ctrl+Alt+G发送到 shell。

当前工作目录检测

壳集成告诉 VS Code 当前 shell 的工作目录是什么。在 Windows 上，没有可能在不尝试通过 regex 检测提示符的情况下获取此信息，并且在 macOS 和 Linux 上需要进行轮询，这对性能不是很好。

其中一个最大的功能是增强终端中链接的解析。点击一个链接package.json例如，当链接激活时，如果禁用了外壳集成，这将打开一个搜索快速选择package.json作为过滤器，如果存在多个package.json工作区中的文件。然而，当启用 shell 集成时，它将打开package.json直接在当前文件夹中读取文件，因为当前位置已知。这允许输出ls例如，可靠地打开正确的文件。

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

扩展的 PowerShell 键盘快捷键

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

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

Ctrl+Space：默认为菜单完成仅在 Windows 系统上
Alt+Space：默认为设置标记在所有平台上
Shift+Enter：默认为添加行在所有平台上
Shift+End：默认为选择行在所有平台上
Shift+Home：默认为选择反向行在所有平台上

增强的可访问性

壳集成向 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是Visual Studio Code在写它们之前。

OSlash;C 633; A ST标记提示开始。
OSCC 633；B ST标记提示结束。
OSlash 633; C ST标记预执行。
OSC 633 ; D [; <退出代码>] ST标记执行已完成，退出代码可选。
OSC 633 ; E ; <命令行> [; <随机数>] ST: 明确设置带有可选随机数的命令行。

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

可选的随机数可以用来验证序列是否来自外壳集成脚本，以防止命令欺骗。当随机数验证成功时，将移除使用命令前的一些保护措施，以改善用户体验。

命令行可以使用\来转义ASCII字符\xAB格式，其中AB是字符代码的十六进制表示（不区分大小写），并转义输入：角色使用输入：\\需要转义半角括号 (0x3b) 和字符 0x20 及以下，这在新行和分号中特别重要。

一些例子：
```
"\"  -> "\\"
"\n" -> "\x0a"
";;"  -> "\x3b"
```
OSC 633 ; P ; 设置终端属性，仅处理已知属性。

已知属性：
- 当前工作目录将当前工作目录报告到终端。
- 是否为Windows: 表示终端是否使用了类似 winpty 或 conpty 的 Windows 后端。这可能会用于启用额外的启发式方法，因为 shell 集成序列的位置不能保证是正确的。有效值是真和假输入：.
- 是否拥有丰富的命令检测: 表示终端是否具有丰富的命令检测能力。此属性设置为真当外壳集成脚本理想地作为 VS Code 所期望的那样工作时，特别是特定序列应在 VS Code 所期望的顺序中出现在预期位置。A, B, E, C, D输入：.

期末考试Shell积分

VS Code 支持 Final Term 的 shell 集成序列，这使得非 VS Code shell 集成脚本可以在 VS Code 中运行。这导致了一种稍微降级的体验，因为它不支持与具体提到的那么多功能。OSlash 633以下是支持的特定序列：

OSC 133；A ST标记提示开始。
OSlash 133; B ST标记提示结束。
OS 133 ; C ST标记预执行。
OSC 133 ; D [; <退出代码>] ST标记执行已完成，退出代码可选。

iTerm2 shell 集成

iTerm2 采用的以下序列受到支持：

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

这些标记与命令导航集成，可以通过 ⌘↑ (Windows, Linux Ctrl+Up) 和 ⌘↓ (Windows, Linux Ctrl+Down) 轻松导航。

常见问题

自动注射在什么情况下不起作用？

有几种情况会导致自动注射不工作，以下是几种常见情况：

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

提示() {
  printf "\033]0;%s@%s:%s\007" "${用户}" "${主机名%%.*}" "${当前目录/#$HOME/\~}"
}
提示命令=提示

一些 shell 插件可能会通过取消设置来明确禁用 VS Code 的 shell 集成$VSCODE_外壳集成当他们初始化。

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

这可能的原因是您的系统安装了另一个终端的 shell 集成，VS Code 会理解。如果您不希望有任何装饰，可以使用以下设置将其隐藏：

"terminal.integrated.shellIntegrationdecorationsEnabled": 永远不

或者，您可以从您的 shell rc/启动脚本中删除 shell 集成脚本，但您将失去诸如命令导航等命令感知功能的访问权限。

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

Windows 使用一个名为 ConPTY 的模拟伪终端 (pty) 后端。它与常规 pty 有点不同，因为它需要与 Windows 控制台 API 保持兼容。这种影响之一是 pty 在渲染方面特殊处理，可能会导致 shell 集成序列错误地识别终端缓冲区中的命令。当命令跳转时，通常是在命令运行之后，VS Code 的启发式算法已启动，以改进命令装饰的位置。