尝试在 VS Code 中使用 ！

终端外壳集成

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

支持的外壳

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

安装

自动脚本注入

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

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

注意：自动注入可能无法在旧版外壳上工作，例如旧版 fish 不支持 $XDG_DATA_DIRS 环境变量，而这是注入的工作方式。您仍然可以手动安装以使其工作。

手动安装

要手动安装外壳集成，VS Code 外壳集成脚本需要在您的外壳初始化期间运行。在哪里以及如何执行此操作取决于您使用的外壳和操作系统。手动安装时，建议将 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)"

可移植性与性能

上述外壳集成安装是跨平台的，并且如果 code 在 $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"

外壳集成质量

使用外壳集成时，它具有一个“质量”与之相关联，该质量声明了它的功能。这些质量取决于外壳集成脚本的行为方式。

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

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

命令装饰和概览标尺

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

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 设置进行配置。

命令导航

外壳集成检测到的命令将提供给命令导航功能（Ctrl/Cmd+向上，Ctrl/Cmd+向下），以提供更可靠的命令位置。此功能允许在命令之间快速导航并选择其输出。要从当前位置选择到命令，您还可以按住 Shift，然后按 Shift+Ctrl/Cmd+向上 和 Shift+Ctrl/Cmd+向下。

命令指南

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

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 反馈提供程序触发时，建议每个建议。

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

运行最近的命令

终端：运行最近命令 命令在快速选择器中显示来自各种来源的历史记录，提供与外壳的反向搜索（Ctrl+R）类似的功能。这些来源包括当前会话的历史记录、此外壳类型的上一个会话历史记录和通用外壳历史文件。

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 发送到外壳。

当辅助功能模式关闭时，可以使用以下键盘快捷方式翻转键盘快捷方式：

{
    "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 发送到外壳。

当前工作目录检测

外壳集成会告诉 VS Code 外壳的当前工作目录是什么。在 Windows 上，不通过正则表达式检测提示符就无法获取此信息，而在 macOS 和 Linux 上则需要轮询，这不利于性能。

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

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

扩展的 PowerShell 键盘快捷方式

Windows 的控制台 API 允许比 Linux/macOS 终端更多的键盘快捷方式，由于 VS Code 的终端即使在 Windows 上也模拟后者，因此有些 PowerShell 键盘快捷方式（例如 Ctrl+空格）由于缺乏 VT 编码而无法使用标准方法实现。外壳集成允许 VS Code 附加自定义键盘快捷方式以向 PowerShell 发送特殊序列，然后该序列在外壳集成脚本中处理并转发给适当的按键处理程序。

当外壳集成启用时，以下键盘快捷方式应在 PowerShell 中工作：

  • Ctrl+空格：仅在 Windows 上默认为 MenuComplete
  • Alt+空格：在所有平台上默认为 SetMark
  • Shift+回车：在所有平台上默认为 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 启用时，git、code 和 code-insiders CLI 的补全功能默认开启。如果您的 PowerShell 配置文件已包含补全功能，您可能希望通过使用 terminal.integrated.suggest.builtinCompletions 设置来关闭它们。

增强的辅助功能

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

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

支持的转义序列

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

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

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

其他终端应忽略这些序列，但除非其他终端更广泛地采用这些序列，否则建议在写入它们之前检查 $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 序列允许终端可靠地获取外壳解释的精确命令行。如果未指定此序列，终端可能会回退到使用 A、B 和 C 序列来获取命令，或者如果不可靠，则完全禁用检测。

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

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

    一些示例

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

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

    已知属性

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

Final Term 外壳集成

VS Code 支持 Final Term 的外壳集成序列，这使得非 VS Code 外壳集成脚本能够在 VS Code 中工作。这会导致体验有所下降，因为它不像 OSC 633 那样支持那么多功能。以下是支持的特定序列：

  • OSC 133 ; A ST：标记提示符开始。
  • OSC 133 ; B ST：标记提示符结束。
  • OSC 133 ; C ST：标记执行前。
  • OSC 133 ; D [; <exitcode>] ST：标记执行完成，可带可选退出代码。

iTerm2 外壳集成

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

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

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

这很可能是因为您的系统安装了另一个终端的外壳集成，而 VS Code 能够识别。如果您不希望显示任何装饰，可以使用以下设置将其隐藏：

"terminal.integrated.shellIntegration.decorationsEnabled": never

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

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

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

06/12/2025