终端 Shell 集成

Visual Studio Code 能够与常用 Shell 集成，从而使终端能够更多地了解 Shell 中实际发生的情况。这些额外信息支持一些有用的功能，例如工作目录检测和命令检测、装饰和导航。

支持的 Shell

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

安装

自动脚本注入

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

这种标准、简单的方式不适用于某些高级用例，例如子 Shell、通过常规 ssh 会话（当未使用 Remote - SSH 扩展时）或某些复杂的 Shell 设置。对于这些情况，启用 Shell 集成的推荐方法是手动安装。

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

手动安装

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

提示： 使用 Insiders 版本时，请将下面的 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 文件中。在 zsh 中运行 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)"

可移植性与性能

上述 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 集成质量

在使用 Shell 集成时，它会关联一个“质量”，该质量声明了其功能。这些质量由 Shell 集成脚本的行为方式决定。

无：未激活任何 Shell 集成。
丰富：Shell 集成已激活，并且命令检测以理想方式工作。
基础：Shell 集成已激活，但命令检测可能不支持所有功能。例如，检测到命令运行位置，但未检测到其退出状态。

要查看 Shell 集成质量，请将鼠标悬停在终端选项卡上。或者，在悬停时选择“显示详细信息”以查看更详细的信息。

IntelliSense

终端中的 IntelliSense 使你能够获得有关文件、文件夹、命令、命令参数和选项的建议。此功能可以通过 terminal.integrated.suggest.enabled 设置进行启用或禁用。

Screenshot of the terminal showing a user has typed git checkout and receives suggestions for the branch name.

当你键入时，将出现建议列表。要手动触发建议，请使用键盘快捷方式。

默认情况下，Tab 键会插入建议。导航列表后，Enter 键会插入建议。你可以使用 terminal.integrated.suggest.selectionMode 设置配置此行为。

有各种设置可以配置终端 IntelliSense 的行为方式

terminal.integrated.suggest.quickSuggestions：根据命令行内容自动显示，而不是通过 Ctrl+Space 手动触发。
terminal.integrated.suggest.suggestOnTriggerCharacters：在“触发字符”之后自动显示，例如 - 或 /。
terminal.integrated.suggest.runOnEnter：使用 Enter 键（而不是 Tab 键）时可选地运行命令。
terminal.integrated.suggest.windowsExecutableExtensions：被视为 Windows 上可执行文件的扩展列表。
terminal.integrated.suggest.providers：提供禁用特定提供程序的能力，例如扩展可能会贡献你不想要的完成。
terminal.integrated.suggest.showStatusBar：在 IntelliSense 弹出窗口底部显示状态栏。
terminal.integrated.suggest.cdPath：启用 $CDPATH 集成。
terminal.integrated.suggest.inlineSuggestion：与 Shell 的“幽灵文本”集成以及如何显示它。
terminal.integrated.suggest.upArrowNavigatesHistory：将向上箭头发送到 Shell 而不是浏览完成项，这在 zsh 中特别有用，因为你可以在过滤后按向上键执行带有该前缀的历史记录搜索。
terminal.integrated.suggest.selectionMode：IntelliSense 弹出窗口的焦点方式，它决定了 Enter 和 Tab 键的作用。
terminal.integrated.suggest.insertTrailingSpace：接受后插入尾随空格并重新触发完成。

全局完成缓存

为了提高性能，VS Code 会为特定 Shell 积极缓存全局项。当你更改 Shell 启动逻辑以添加命令时，请使用 **Terminal: Clear Suggest Cached Globals** 命令（terminal.integrated.suggest.clearCachedGlobals）手动刷新缓存，如果它们未自动拾取。

命令装饰和概览标尺

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

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

命令和概览标尺装饰可以通过 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 反馈提供程序时，建议每个建议。

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

运行最近的命令

Terminal: Run Recent Command 命令会在快速选取器中显示来自各种来源的历史记录，提供与 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 将 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"
}

转到最近的目录

与运行最近命令功能类似，**Terminal: Go to Recent Directory** 命令会跟踪访问过的目录，并允许快速过滤和导航（cd）到这些目录。Alt 键可以按住以将文本写入终端而不执行。

此命令的默认键盘快捷方式是 ⌘G (Windows, Linux Ctrl+G)，因为它类似于编辑器中的“转到行/列”命令。可以通过 Ctrl+Alt+G 将 Ctrl+G 发送到 Shell。

当前工作目录检测

Shell 集成将 Shell 的当前工作目录信息告知 VS Code。在 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 编码，某些 PowerShell 键盘快捷方式无法通过标准方式实现，例如 Ctrl+Space。Shell 集成允许 VS Code 附加自定义键盘快捷方式，以发送一个特殊序列到 PowerShell，然后由 Shell 集成脚本处理并转发到正确的键处理程序。

启用 Shell 集成后，以下键盘快捷方式应在 PowerShell 中工作

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

增强的可访问性

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：显式设置命令行，并可选提供 nonce。

E 序列允许终端可靠地获取 Shell 解析的确切命令行。当未指定此序列时，终端可能会回退到使用 A、B 和 C 序列来获取命令，或者在检测不可靠时完全禁用检测。

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

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

一些示例
```
"\"  -> "\\"
"\n" -> "\x0a"
";"  -> "\x3b"
```
OSC 633 ; P ; <Property>=<Value> ST：在终端上设置属性，仅处理已知的属性。

已知属性
- Cwd：向终端报告当前工作目录。
- IsWindows：指示终端是否正在使用 Windows 后端，如 winpty 或 conpty。这可能用于启用额外的启发式方法，因为 Shell 集成序列的位置不能保证正确。有效值为 True 和 False。
- HasRichCommandDetection：指示终端是否具有丰富的命令检测功能。当 Shell 集成脚本以 VS Code 期望的理想方式运行时，此属性将设置为 True，特别是序列应以 A, B, E, C, D 的顺序出现在预期位置。

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：在触发该序列的行的左侧添加标记，并在滚动条中添加注释。

这些标记与命令导航集成，以便通过 ⌘↑ (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 可以理解。如果你不想要任何装饰，可以使用以下设置隐藏它们：

"terminal.integrated.shellIntegration.decorationsEnabled": never

或者，你可以从 Shell rc/startup 脚本中删除 Shell 集成脚本，但你将失去对命令感知功能（如命令导航）的访问权限。

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

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

12/10/2025