zsh-autosuggestions 完整設定教學：打字速度直接快一倍

你每天打最多次的指令，可能就是那十幾二十個——git pull、docker-compose up -d、kubectl get pods -n prod。

每次都要完整打完，有點浪費。

zsh-autosuggestions 做的事情是：根據你的歷史記錄，在你打字的時候用灰色文字預測後面的內容——你覺得對了，按一個鍵直接補完，不用完整打完。

用過三天之後，你會發現自己回到沒裝的環境，手指會停在那邊等一下——因為預測沒出來。

TL;DR

設定項	推薦值	說明
安裝方式	git clone + plugins	標準安裝，最穩
補完快捷鍵	`→`（右方向鍵）	補完整行
補完單字	`Ctrl+→` 或自訂	只補下一個字
預測策略	`history`（預設）	從歷史找，夠用
高優先歷史策略	`match_prev_cmd`	從上一個指令的前後關係找
建議文字顏色	`fg=244` 或 `fg=8`	根據你的主題調
停用自動建議	`ZSH_AUTOSUGGEST_CLEAR_WIDGETS`	某些指令打完自動清掉建議

安裝

如果已經跟著 02-plugins 裝好了，這段可以跳過。

git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

然後在 ~/.zshrc 的 plugins=() 加進去：

plugins=(git z sudo zsh-autosuggestions zsh-syntax-highlighting)

source ~/.zshrc

裝完之後開始打指令，灰色文字就會出現了。

補完快捷鍵

預設是按右方向鍵 → 補完整行建議。對大多數人夠用，但如果你習慣用方向鍵左右移動游標，可能會衝突——這種情況就要自訂。

補完整行（預設）

# ~/.zshrc
bindkey '→' autosuggest-accept

補完單個字（只接受下一個 word）

bindkey '^→' forward-word   # Ctrl+右鍵

用 End 鍵補完（某些人偏好）

bindkey "${terminfo[kend]}" autosuggest-accept

把 Ctrl+F 設為補完（不影響方向鍵）

bindkey '^F' autosuggest-accept

這個我用了一段時間，Ctrl+F 原本在 Vim 裡是 Page Down，但在 Zsh 裡沒有衝突，補完手感很順。

改完一樣 source ~/.zshrc，馬上生效。

預測策略

zsh-autosuggestions 有兩種找建議的策略，可以單獨用，也可以組合：

`history`（預設）

從你的歷史記錄裡找最近一次匹配的指令。簡單、快、多數情境夠用。

ZSH_AUTOSUGGEST_STRATEGY=(history)

`match_prev_cmd`

除了看你打的前綴，還會考慮你上一條指令是什麼——根據脈絡預測你現在要打什麼。

舉個例子：你剛打完 git add .，接著開始打 git，它會優先建議 git commit -m "..." 而不是其他 git 指令，因為 add 後面最常見的就是 commit。

ZSH_AUTOSUGGEST_STRATEGY=(match_prev_cmd history)

陣列的順序就是優先順序，match_prev_cmd 找不到才 fallback 到 history。

`completion`（實驗性）

直接呼叫 Zsh 的補完引擎來生成建議，不是從歷史裡找。這個比較吃效能，啟動和補完都會感覺慢一點——除非有特殊需求，建議先不開。

ZSH_AUTOSUGGEST_STRATEGY=(history completion)  # 組合使用

建議文字顏色

預設的灰色在深色主題下通常沒問題，但淺色主題可能看不清楚，或是跟你的 Powerlevel10k 顏色搭不好。

# ~/.zshrc，加在 plugins 之前的某處
 
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=244"          # 淺灰，深色主題推薦
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=8"            # 暗灰，更保守
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#666666"      # 直接指定 hex（需終端支援 truecolor）
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=244,underline" # 底線版，更明顯

顏色編號 fg=0 到 fg=255 對應標準 256 色終端。如果你不確定哪個好看，fg=244 是最安全的選項。

讓某些情況自動清除建議

有時你打完一條指令、按下 Enter 之後，下一行冒出來的建議是完全無關的東西——讓版面變亂。可以設定哪些操作會自動清掉當前建議：

ZSH_AUTOSUGGEST_CLEAR_WIDGETS+=(
  history-beginning-search-backward-end
  history-beginning-search-forward-end
)

這個設定告訴它：當你用歷史搜尋在翻指令時，清掉當前建議。不然翻歷史的時候，建議文字和游標之間會出現奇怪的覆蓋。

效能：非同步模式

Zsh 5.0.8 以上的版本，zsh-autosuggestions 預設就是用非同步方式找建議——找建議的過程不會卡住你打字。

如果你的 Zsh 比較舊，或是想確認有沒有開啟：

ZSH_AUTOSUGGEST_USE_ASYNC=1

另外，歷史記錄如果非常大（幾萬條），搜尋建議本身也可能變慢。這個可以限制建議搜尋的最大字元長度，避免對超長指令做完整匹配：

ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20

超過 20 個字元的輸入就不顯示建議，這樣對長指令的效能影響降到最低。

常見問題

建議文字不出現

確認 zsh-autosuggestions 有在 plugins=() 裡
確認有 clone 到 ${ZSH_CUSTOM}/plugins/zsh-autosuggestions
跑 source ~/.zshrc 重載
打幾條指令建立歷史記錄再試——新安裝的 Zsh 歷史記錄是空的，沒有東西可以建議

tmux 裡建議顏色變怪

tmux 的顏色支援和終端機本身不同，可能把 fg=244 算錯。試試改成更基礎的：

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=8"

或確認 tmux 設定裡有：

set -g default-terminal "screen-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

SSH 連線裡建議補完沒反應

這通常是 bindkey 的問題——SSH 終端機傳過來的 key code 可能不一樣。確認你的 bindkey 設定，或改用字符而不是 terminfo 對應：

bindkey '^F' autosuggest-accept   # Ctrl+F，比較不受終端機影響

建議一直跳到我不想要的指令

歷史記錄裡有一些你很久以前打的長指令一直被預測出來，但現在用不到。清一下歷史：

# 直接編輯歷史檔案（通常在 ~/.zsh_history）
# 刪掉你不想要的行
# 或用這個指令搜尋並確認刪除
fc -R && history | grep "那個煩人的指令"

完整設定範例

把以下內容貼到 ~/.zshrc 的外掛載入之後（source $ZSH/oh-my-zsh.sh 之後）：

# zsh-autosuggestions 設定
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=244"
ZSH_AUTOSUGGEST_STRATEGY=(match_prev_cmd history)
ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20
ZSH_AUTOSUGGEST_USE_ASYNC=1
 
# 補完快捷鍵
bindkey '^F' autosuggest-accept          # Ctrl+F 補完整行
bindkey '^[→' forward-word               # Alt+右鍵 補完單字（macOS 可能要另外設定）
 
# 翻歷史時清掉建議
ZSH_AUTOSUGGEST_CLEAR_WIDGETS+=(
  history-beginning-search-backward-end
  history-beginning-search-forward-end
)

存檔、source ~/.zshrc，打幾條指令讓歷史有東西，然後試試看。

設定好之後，繼續 04-themes：終端機的資訊密度不輸給 IDE 的 Powerlevel10k 設定。