參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

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

可移植性與效能

如果 code 在 $PATH 中，上述 shell 整合安裝是跨平臺的，並與任何安裝型別相容。然而，這種推薦的方法會啟動 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)以檢視更詳細的資訊。

命令裝飾器和概覽標尺

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

可以與裝飾器進行互動，以執行一些上下文相關的操作，例如重新執行命令。

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 設定進行配置。

命令導航

由 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 會掃描命令的輸出，並提供一個快速修復（Quick Fix）建議，其中包含使用者接下來最可能想要執行的操作。

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)，因為它的行為類似於編輯器中的轉到行/列 (Go to Line/Column)命令。可以使用 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 上也模擬後者，因此有些 PowerShell 鍵盤快捷鍵（如 Ctrl+Space）由於缺少 VT 編碼而無法透過標準方式實現。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)）
  • 當命令失敗時會播放聲音提示。
  • 底層的文字框同步，使得使用箭頭鍵和退格鍵的行為更加正確。

智慧感知 (預覽)

終端中的智慧感知（IntelliSense）使你能夠接收檔案、資料夾、命令、命令引數和選項的建議。此功能由 shell 整合 terminal.integrated.shellIntegration.enable 提供支援，並可以透過 terminal.integrated.suggest.enabled 啟用。

A user has typed git checkout in a terminal and requests completions. The completion list shows branch names like main and merogge/terminal-section

VS Code 從 Fig 規範中獲取命令，並根據 $PATH 驗證每個 shell 的內建函式（適用於 pwsh、bash、zsh 和 fish），以確保它們存在。在 Windows 上，你可以使用 terminal.integrated.suggest.windowsExecutableExtensions 設定來配置特定的可執行檔案集。

鍵盤導航

預設情況下，Tab 鍵插入建議。一旦在列表中進行了導航，Enter 鍵也會同樣插入建議。你可以使用 terminal.integrated.suggest.selectionMode 設定來配置此行為。

要在接受建議時既插入又在終端中執行它，請配置 terminal.integrated.suggest.runOnEnter。

智慧感知可以透過 ⌃Space (Windows, Linux Ctrl+Space) 手動觸發，也可以在輸入時觸發，後者可以透過 terminal.integrated.suggest.quickSuggestions 停用。當輸入特定字元（例如 /）時也可以觸發智慧感知，這可以透過 terminal.integrated.suggest.suggestOnTriggerCharacters 進行配置。

當 shell 提供內聯補全時，VS Code 會將其作為列表中的第一個補全項顯示。你可以使用 terminal.integrated.suggest.inlineSuggestion 設定來進一步配置此行為。

設定 terminal.integrated.suggest.showStatusBar 控制是否在列表底部顯示狀態列。該狀態列提供瞭解更多（⇧⌘L (Windows, Linux Ctrl+Shift+L)）、插入（Tab）和配置（⇧⌘, (Windows, Linux Ctrl+Shift+,)）等操作。在你初次使用智慧感知功能時，瞭解更多操作會高亮顯示，以提高可發現性。

建議控制元件可以顯示關於建議的額外詳細資訊。你可以使用 ⌃Space (Windows, Linux Ctrl+Space) 切換這些詳細資訊的可見性。螢幕閱讀器使用者可以使用 ⌃⌥Space (Windows, Linux Ctrl+Alt+Space) 聚焦到詳細資訊控制元件以聽取其朗讀。

全域性補全快取

為了提高效能，VS Code 會為特定的 shell 積極快取全域性變數。當你對新增命令的 shell 啟動邏輯進行更改，並且這些更改沒有被自動檢測到時，請使用終端：清除建議快取的全域性變數 (Terminal: Clear Suggest Cached Globals) 命令（terminal.integrated.suggest.clearCachedGlobals）手動重新整理快取。

支援的轉義序列

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：在觸發它的行的左側新增一個標記，並在捲軸上新增一個註釋。

    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

  • 一些 shell 外掛可能會在初始化時透過取消設定 $VSCODE_SHELL_INTEGRATION 來明確停用 VS Code 的 shell 整合。

為什麼在停用該功能時命令裝飾器仍然顯示？

這很可能是因為你的系統上安裝了另一個終端的 shell 整合，而 VS Code 能夠理解它。如果你不想要任何裝飾器，可以使用以下設定隱藏它們：

"terminal.integrated.shellIntegration.decorationsEnabled": never

或者，你可以從你的 shell rc/啟動指令碼中移除 shell 整合指令碼，但你將無法使用命令感知功能，如命令導航。

為什麼在 Windows 上命令裝飾器會跳動？

Windows 使用一個名為 ConPTY 的模擬偽終端（pty）後端。它的工作方式與常規 pty 有些不同，因為它需要保持與 Windows 控制檯 API 的相容性。其中一個影響是，pty 以特殊方式處理渲染，導致用於識別終端緩衝區中命令的 shell 整合序列可能會錯位。當命令跳動時，通常是在命令執行後，VS Code 的啟發式演算法啟動以改善命令裝飾器的位置。

09/11/2025