终端 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 在 VS Code 中打开在 VS Code Insiders 中打开设置为 false 来禁用此自动注入。

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

注意：自动注入可能在旧版本的 Shell 上无法正常工作，例如较旧版本的 fish 不支持 $XDG_DATA_DIRS 环境变量（注入依赖于此）。你可能仍然可以通过手动安装来使其工作。

Windows 注意事项：VS Code Shell 集成需要运行 PowerShell 脚本的权限。如果你独占使用计算机上的用户帐户，请考虑运行
if ((Get-ExecutionPolicy -Scope LocalMachine) -eq 'Undefined' -and (Get-ExecutionPolicy -Scope CurrentUser) -eq 'Undefined') {
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
}

手动安装

要手动安装 Shell 集成，需要在 Shell 初始化期间运行 VS Code Shell 集成脚本。在哪里以及如何做到这一点取决于你使用的 Shell 和操作系统。使用手动安装时，建议将 terminal.integrated.shellIntegration.enabled 在 VS Code 中打开在 VS Code Insiders 中打开设置为 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 集成脚本的行为决定。

无 (None)：没有激活的 Shell 集成。
丰富 (Rich)：Shell 集成已激活，且命令检测正以理想的方式工作。
基础 (Basic)：Shell 集成已激活，但命令检测可能不支持所有功能。例如，可以检测到命令运行位置，但检测不到其退出状态。

要查看 Shell 集成质量，请将鼠标悬停在终端选项卡上。或者，在悬停提示上选择显示详情 (Show Details) 以查看更详细的信息。

IntelliSense

终端中的智能感知 (IntelliSense) 允许你接收有关文件、文件夹, 命令、命令参数和选项的建议。可以通过 terminal.integrated.suggest.enabled 在 VS Code 中打开在 VS Code Insiders 中打开设置启用或禁用此功能。

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

键入时，将出现建议列表。要手动触发建议，请使用 ⌃Space（Windows、Linux 为 Ctrl+Space）快捷键。

提示

Ctrl+Space 可能是用于在操作系统级别触发输入法编辑器 (IME) 的快捷键。如果是这样，你可以使用自定义快捷键重新绑定 workbench.action.terminal.triggerSuggest 命令，或者更改操作系统级别的快捷键。

默认情况下，Tab 键会插入建议。浏览列表后，Enter 键会插入建议。你可以通过 terminal.integrated.suggest.selectionMode 在 VS Code 中打开在 VS Code Insiders 中打开设置来配置此行为。

有各种设置可用于配置终端智能感知的行为

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

全局补全缓存

为了提高性能，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 在 VS Code 中打开在 VS Code Insiders 中打开设置来配置命令和概览标尺装饰。

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 在 VS Code 中打开在 VS Code Insiders 中打开设置。

粘性滚动

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

Sticky scroll will show the command at the top of the terminal viewport

可以通过 terminal.integrated.stickyScroll.enabled 在 VS Code 中打开在 VS Code Insiders 中打开设置启用此功能。

快速修复

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 在 VS Code 中打开在 VS Code Insiders 中打开设置决定。

此命令的默认快捷键是 Ctrl+Alt+R。但是，当无障碍模式开启时，这些快捷键会相反；Ctrl+R 运行最近的命令，而 Ctrl+Alt+R 向 Shell 发送 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"
}

转到最近的目录

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

此命令的默认快捷键是 ⌘G（Windows、Linux 为 Ctrl+G），因为它的行为类似于编辑器中的转到行/列命令。可以通过 Ctrl+Alt+G 将 Ctrl+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：仅在 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 序列来获取命令，或者如果不可靠则完全禁用检测。

可选的随机数可用于验证该序列来自 Shell 集成脚本，以防止命令欺骗。当随机数验证成功时，将删除使用命令前的某些保护措施，以改善用户体验。

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

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

已知属性
- Cwd：向终端报告当前工作目录。
- IsWindows：指示终端是否正在使用诸如 winpty 或 conpty 之类的 Windows 后端。这可用于启用额外的启发式方法，因为 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> 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 插件可能会在初始化时取消设置 $VSCODE_SHELL_INTEGRATION，从而显式禁用 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 的启发式算法已介入以改善命令装饰的位置。

7/29/2026