終端 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