終端機 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 環境變數。您仍可嘗試手動安裝以使其運作。

手動安裝

若要手動安裝 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 整合品質，請將滑鼠游標懸停在終端機索引標籤上。或者，選取懸停視窗中的顯示詳細資料以檢視更多資訊。

IntelliSense

終端機中的 IntelliSense 可讓您接收關於檔案、資料夾、指令、指令引數與選項的建議。此功能可透過 terminal.integrated.suggest.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定啟用或停用。

當您輸入時，會出現建議清單。若要手動觸發建議，請使用 ⌃Space (Windows, Linux 為 Ctrl+Space) 鍵盤快速鍵。

預設情況下，Tab 鍵會插入建議。瀏覽清單後，Enter 鍵會插入建議。您可以透過 terminal.integrated.suggest.selectionMode 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來設定此行為。

有多種設定可調整終端機 IntelliSense 的行為：

• 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 中開啟 ：在 IntelliSense 快顯視窗底部顯示狀態列。
• terminal.integrated.suggest.cdPath 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ：啟用 $CDPATH 整合。
• terminal.integrated.suggest.inlineSuggestion 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ：整合 Shell 「幽靈文字」(ghost text) 及呈現方式。
• terminal.integrated.suggest.upArrowNavigatesHistory 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ：將向上鍵傳送至 Shell 而非瀏覽補完建議。這在 zsh 上特別有用，您可以篩選後按下向上鍵來執行該前綴的歷史紀錄搜尋。
• terminal.integrated.suggest.selectionMode 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ：Intellisense 快顯視窗的焦點方式，決定了 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 整合啟用的其中一項功能是能夠取得在終端機中執行指令的結束代碼。利用此資訊，可在該行左側加入裝飾，以指出指令是否成功或失敗。這些裝飾也會如同編輯器一樣，顯示在捲軸較新的概覽尺中。

可與這些裝飾互動以提供一些關聯式動作，例如重新執行指令。

指令與概覽尺裝飾可透過 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 整合是否正常運作的一種方式。

您可以使用色彩佈景主題來自訂指令指南的顏色。若要切換指令指南，請配置 terminal.integrated.shellIntegration.showCommandGuide 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定。

黏滯捲動 (Sticky scroll)

黏滯捲動功能會將部分顯示在終端機頂部的指令「黏住」，讓您更容易查看該輸出屬於哪個指令。點擊黏滯捲動元件將會捲動至終端機緩衝區中該指令的位置。

此功能可透過 terminal.integrated.stickyScroll.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來啟用。

快速修正

VS Code 會掃描指令的輸出，並顯示「快速修正」，提供使用者極有可能想要執行的後續動作。

以下是一些內建的快速修正：

• 偵測到連接埠已被佔用時，建議終止該程序並重新執行上一個指令。
• 當 git push 因未設定上游 (upstream) 而失敗時，建議在設定上游的同時進行推送。
• 當 git 子指令因類似指令錯誤而失敗時，建議使用該類似指令。
• 當 git push 產生建立 GitHub PR 的建議時，建議開啟該連結。
• 當 General 或 cmd-not-found PowerShell 回饋提供者觸發時，建議各項補完選項。

快速修正功能也支援協助工具訊號，在快速修正可用時提供額外的回饋。

執行最近指令

Terminal: Run Recent Command 指令會在「快速挑選」(Quick Pick) 中顯示來自各種來源的紀錄，提供類似 Shell 反向搜尋 (Ctrl+R) 的功能。來源包含目前工作階段的紀錄、此類 Shell 之前的紀錄，以及通用的 Shell 紀錄檔案。

該指令的其他功能：

• 預設搜尋模式為「連續搜尋」(contiguous search)，表示搜尋詞彙必須完全相符。搜尋輸入框右側的按鈕可切換為模糊搜尋。
• 在目前工作階段區段，快速挑選右側有一個剪貼簿圖示，點擊後會在編輯器中開啟指令輸出。
• 快速挑選右側的釘選動作可將指令固定在清單頂部。
• 按住 Alt 可將文字寫入終端機而不執行它。
• 上一個工作階段區段中儲存的紀錄數量，由 terminal.integrated.shellIntegration.history 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定決定。

此指令的預設快速鍵為 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+G 可透過 Ctrl+Alt+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 編碼，有些 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))
• 當指令失敗時播放音訊提示。
• 同步底層文字方塊，使箭頭鍵和倒退鍵的運作更加正確。

支援的跳脫序列 (Escape sequences)

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：標記預執行 (pre-execution)。

• 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> 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/啟動指令碼中移除 Shell 整合指令碼，但您將失去對「指令感應」功能的存取權，如指令巡覽。

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

Windows 使用稱為 ConPTY 的模擬虛擬終端機 (pty) 後端。它的運作方式與一般的 pty 有些不同，因為它需要保持與 Windows 主控台 API 的相容性。其中一個影響是 pty 處理渲染的特殊方式，導致標識終端機緩衝區中指令的 Shell 整合序列可能會被錯置。當指令跳動時，通常發生在指令執行之後，且 VS Code 的啟發式方法已介入以改善指令裝飾的位置。