如何修正 SSH 的 unknown terminal type 錯誤
SSH 傳送的 TERM 名稱若不在伺服器 terminfo 資料庫中,curses 程式就會失敗。將 terminfo 編譯到家目錄即可修正,無需 root 權限。
「unknown terminal type」的含義
透過 SSH 遇到「unknown terminal type」錯誤,表示 TERM 中的名稱在伺服器上的 terminfo 資料庫找不到相符項目。終端機模擬器會在您的筆電上設定這個名稱。實際上需要辨識該名稱的資料庫位於遠端電腦。查詢失敗時,該伺服器上的所有 curses 程式都會在繪製任何內容前停止,因為它沒有描述您終端機功能的資訊。
若要保留終端機模擬器的所有功能,只需執行一個指令:將自己的 terminfo 項目編譯到伺服器上的 ~/.terminfo。在 Debian 等標準建置中,ncurses 會先搜尋您的家目錄,再搜尋任何系統目錄(只有在設定 $TERMINFO 變數時,才會先檢查該變數指定的位置),因此不需要 root,也不會變更其他使用者的設定。ncurses 對家目錄的查詢屬於選用功能,因此修正後的檢查很重要。
TERM 是名稱,terminfo 是資料庫
TERM 儲存一個字串,而該字串僅是索引鍵。terminfo 是由終端機描述組成的編譯資料庫,程式會透過這個索引鍵尋找正確的描述。描述內容包括終端機支援的色彩數量、將游標移至第 12 列第 40 欄所需的位元組、F5 按鍵送出的位元組,以及是否能繪製具樣式的底線。Linux 上幾乎所有文字使用者介面都建置於其上的 ncurses 程式庫,會在啟動時讀取這項描述。top、less、nano 和 watch 等程式若沒有這項描述,便無法繪製任何畫面。
查看您自己的項目:
echo "$TERM"
tput longname
infocmp -1 | head -20tput longname 會列印 TERM 所指定項目的人類可讀描述。對於 xterm-256color,它會列印:
xterm with 256 colorsinfocmp -1 會反組譯該項目,並逐行列印各項功能。除非加入 -x,否則它不會列出擴充功能(使用者定義的功能),例如 infocmp -1 -x。如果兩個指令都能正常執行,表示這台機器上的資料庫認得此終端機。透過 SSH 連線時,遠端端也必須具備相同狀態。
為什麼只有透過 SSH 才會發生問題
SSH 只會傳送名稱,不會傳送其他內容。用戶端要求虛擬終端機時,TERM 會隨該要求傳送。OpenSSH 手冊明確指出:「每當要求虛擬終端機時,一律會傳送 TERM 環境變數,因為通訊協定需要此變數。」因此,VPS 上的登入 shell 會取得 TERM=xterm-ghostty、xterm-kitty,或終端機模擬器使用的其他名稱。該名稱所對應的描述仍位於筆記型電腦及其資料庫中。在終端機模擬器問世前建立的伺服器,從未聽過這個名稱。SSH 連線本身不會複製終端機描述,這是刻意的設計:通訊協定會傳送名稱,而不是完整的功能清單。
在自己的電腦上使用確定不存在的名稱,即可重現這項問題:
TERM=xterm-nosuchthing tput colors
echo "$?"tput: unknown terminal "xterm-nosuchthing"退出狀態為 3。tput 手冊將其說明為「未辨識的終端機類型」。每個 curses 程式都會執行相同的查詢,因此缺少一個名稱時,各程式會顯示不同訊息,但根本原因相同。nano 會以 Error opening terminal: xterm-nosuchthing. 結束;這是 ncurses 無法在啟動時載入描述時的標準錯誤。vim 會顯示 E558: Terminal entry not found in terminfo。less 會顯示 WARNING: terminal is not fully functional。看似部分正常運作的分頁器,以及拒絕啟動的編輯器,可能會被誤認為是彼此無關的錯誤。實際上,它們都缺少同一個檔案。
ncurses 尋找項目的位置
ncurses 會依固定順序搜尋,詳情記載於 terminfo(5):
$TERMINFO(如果已設定)。這個位置最先檢查。$HOME/.terminfo。手冊稱這是「可完全從函式庫省略的選用功能」,也可以限制特權程式,避免程式意外使用這項功能。$TERMINFO_DIRS中列出的每個目錄。- 編譯時內建的位置。在 Debian 和 Ubuntu 上,包含
/etc/terminfo、/lib/terminfo和/usr/share/terminfo。
請在伺服器上執行 infocmp -D,列出該伺服器所使用的 ncurses 建置版本中的搜尋路徑,不要直接假設上述路徑正確。關鍵在第 2 步。Debian 的 ncurses 建置版本未停用這項功能。只要該位置存在,ncurses 就會先搜尋您的家目錄,再搜尋任何系統目錄。因此,只要在 ~/.terminfo 下放置一個檔案,就能修正您帳戶的查找結果,不需要安裝套件,也不需要 root 權限。修正後執行 tput longname,即可確認伺服器上的建置版本是否支援這項行為。唯一的例外是第 1 步:如果 echo "$TERMINFO" 在伺服器上輸出某個位置,ncurses 會先檢查該位置;若其中有同名項目,就會優先使用該項目,而不是您放置的項目。
修正 1:使用伺服器已知的 TERM
最快的解除阻塞方式,是為單次連線指定其他終端機:
TERM=xterm-256color ssh user@203.0.113.10若要對該主機永久套用,請在筆電的 ~/.ssh/config 中設定:
Host vps1
HostName 203.0.113.10
User deploy
SetEnv TERM=xterm-256color使用 SetEnv 覆寫 TERM,需要用戶端執行 OpenSSH 8.7 或更新版本;該版本於 August 2021 發布。較舊的用戶端不論是否設定這一行,都會傳送終端機模擬器本身的 TERM。TERM 是唯一不需要伺服器允許的變數:手冊指出:「與 SendEnv 類似,但 TERM 變數除外,伺服器必須準備好接收該環境變數。」因此,即使連線到完全未設定 AcceptEnv 的強化 sshd,這項設定仍然有效。
代價是:終端機模擬器所描述、超出純 xterm-256color 的所有功能都會無法使用。其中包括透過 RGB capability 宣告的 24-bit 色彩,以及透過 Smulx 設定的樣式底線。依賴 terminfo 項目的程式將無法再看到這些 capability,因此會退回使用 256 色與一般底線,除非你另外設定程式直接傳送這些控制序列。例如,Vim 仍可透過 set termguicolors 繪製 24-bit 色彩,因為其內建的 t_8f 與 t_8b 控制序列適用於大多數終端機。畫面仍能正常顯示,只是功能不如你選用的終端機完整。
不要在伺服器的 .bashrc 中加入 export TERM=xterm-256color 來解決這個問題。該檔案會套用到每個連線,包括來自伺服器已知其名稱之終端機的連線,因此會讓原本正常的工作階段降級。請將覆寫設定保留在用戶端,因為你知道自己使用的是哪一個終端機模擬器。
修正 2:將 terminfo 項目傳送到伺服器一次
這是能保留終端模擬器設定的修正方式。在本機反編譯該項目,透過 SSH 傳送,再在遠端主機編譯:
infocmp -x | ssh user@203.0.113.10 -- tic -x -infocmp -x會將目前 TERM 的項目輸出為原始碼文字,其中包含延伸功能(使用者自訂功能)。tic -x會在伺服器上將該原始碼重新編譯為二進位描述。兩端的 -x 都很重要,因為沒有它,Smulx 等功能會在傳輸過程中遭到捨棄,傳送過去的會是自己終端機的降級版本。
tic在有權限時會寫入系統目錄;如果使用者沒有該目錄的寫入權限,則改用 $HOME/.terminfo。VPS 上的普通帳號會使用家目錄,這正是所需的結果。也可以指定目的地:
infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdin~/.terminfo外的引號不是裝飾。ssh會將命令字組合成單一字串,再交給遠端 shell,因此未加引號的 ~ 會先由本機 shell 展開。接著你會將字面上的 /home/yourname/.terminfo 傳送到另一台伺服器,而該伺服器上的帳號名稱可能不同。tic會因權限錯誤而失敗,或寫入 ncurses 不會搜尋的路徑。將波浪號加上引號,讓遠端 shell 展開它。
登入並檢查:
ssh user@203.0.113.10
tput longname
ls -R ~/.terminfotput longname列印終端機描述,表示查找已成功;ls則會顯示編譯後的檔案位於以終端機名稱首字母命名的子目錄中。接著執行 top,或使用 watch -n1 uptime 監控;它會透過相同的函式庫重新繪製畫面,確認實際的 curses 程式能正確繪製畫面。
代價是:每台伺服器都要執行一次,而且該項目只存在某台機器上某個帳號的家目錄中。VPS 重建後,項目就會消失。將此命令加入你用來一次佈建及管理多台伺服器的工具中,讓新主機建立後就已完成項目編譯。
修正方法 3:安裝擴充 terminfo 資料庫
如果你具備 root 權限,並希望所有帳戶都能解析該名稱:
sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longnamencurses-term 包含基本安裝所省略的終端機描述。它會為 root 及其他所有使用者修正該名稱;修正方法 2 無法做到這點。
只有在你使用的終端機項目存在於發行版所封裝的 ncurses 版本中時,這個方法才有效。因此,請先檢查,不要直接假設。Ubuntu 24.04 隨附 ncurses-bin 6.4+20240113-1ubuntu2.2(截至 2026 年 11 月)。Ghostty 的項目是在上游 ncurses 6.5-20241228 中加入的,版本較新;因此,Ubuntu 24.04 上的 apt install ncurses-term 無論執行多少次,都無法產生 xterm-ghostty 項目。tput -T <name> longname 可用來檢查:項目存在時會輸出其描述;項目不存在時則會輸出 unknown terminal,並以結束狀態 3 結束。
若要只安裝單一項目,而不是安裝整個套件,請以 root 身分複製來源檔並進行編譯:
infocmp -x | ssh user@203.0.113.10 -- 'cat > /tmp/term.src'
ssh -t user@203.0.113.10 -- sudo tic -x -o /usr/share/terminfo /tmp/term.src第二個命令中的 -t 會配置虛擬終端機,讓 sudo 能夠提示輸入密碼。若沒有這個選項,ssh 不會為遠端命令配置終端機;需要密碼時,sudo 會因 sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper 而停止。該錯誤是因為缺少 tty,不是 terminfo 的問題。
讓終端模擬器執行傳輸
部分終端模擬器提供可自動套用修正 2 的輔助功能。kitty 有一個 ssh kitten:kitten ssh myserver 會自動連線,並將 kitty 的 terminfo 複製到遠端主機。其文件也提供手動形式 infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin;其中的波浪號已逸出,原因如上所述。Ghostty 的文件記載 infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -。自 1.2.0 版起,Ghostty 提供可選用的 shell integration 功能(ssh-env 和 ssh-terminfo),可自動套用這兩項修正。Ghostty 1.4.0 於 October 27, 2026 發布,新增 1.3.x releases 沒有的 ghostty +ssh wrapper,現在這兩項可選功能會呼叫它。它會在建立連線前,將 Ghostty 隨附的 terminfo 安裝到遠端主機;若安裝失敗,例如伺服器沒有 tic,則改用 TERM=xterm-256color。在 1.4 版中,ssh-env 也不再覆寫 ~/.ssh/config 中的 SetEnv 行,因此會遵循修正 1 中針對特定主機的覆寫設定。
這些輔助功能執行的命令,與剛才手動執行的命令相同。了解手動形式仍然重要,因為連線若從其他位置開始,例如跳板主機或指令碼內,輔助功能便無法執行。
錯誤再次出現時
在 sudo -i 下。 以 root 身分啟動的登入 shell 具有 HOME=/root,而 sudo 會保留你的 TERM。因此,ncurses 現在會搜尋 /root/.terminfo;該位置沒有你的項目,所以只有 root 會再次發生錯誤。使用 sudo -i env 確認,並讀取 HOME 與 TERM 行。將該項目安裝到系統目錄。放在 /root/.terminfo 的副本也可能有效,但 ncurses 可能會限制特權程序對家目錄的查找,因此請以 root 身分執行 tput longname 進行確認。
在 tmux 或 screen 內。 這些程式會為其中執行的程式設定自己的 TERM,通常是 screen-256color 或 tmux-256color。較舊的伺服器知道 screen-256color,但可能不認得 tmux-256color,因此外層 shell 運作正常,而工作階段內的所有程式都會失敗。原因相同,只是名稱不同。在伺服器上執行 tput -T tmux-256color longname,查看它具備其中哪一個。以 tmux 為基礎的終端工作台 為例,這個問題會一直被隱藏,直到你在尚未修正的主機上進行連線。
在新的伺服器上。 ~/.terminfo 以帳號和機器為單位,因此重建 VPS 後又會恢復為空白。
畫面正常,但按鍵行為異常。 如果畫面顯示正常,但 Home、End 或功能鍵會插入多餘字元,表示解析出的名稱對應到與終端機不相符的項目。按鍵序列和畫面繪製能力來自相同的 terminfo 項目,因此近似的項目只能提供近似的按鍵行為。這通常是因為在按鍵序列不同於 xterm 的模擬器上採用修正 1。修正 2 是最乾淨的解決方式,因為模擬器的實際項目會為所有程式一次提供正確的按鍵序列。這不是唯一的方法:Vim 文件指出,你可以「使用 :set 命令變更按鍵代碼」;Vim 會在啟動時直接向新版 xterm 詢問按鍵代碼,而不是只依賴該項目。
FAQ
為什麼透過 SSH 連線時只看到「unknown terminal type」?
因為必須包含終端機項目的資料庫位於伺服器上。終端機模擬器會將描述安裝在自身執行的機器上,因此本機程式無須額外設定即可找到。SSH 只會傳送 TERM 的值,因為該通訊協定會在 pseudo-terminal 請求中攜帶這個名稱。遠端 ncurses 會在遠端資料庫中查詢該名稱,但找不到項目,因此 initscr 失敗,程式也會停止。
沒有伺服器上的 root 權限時,可以修正這個問題嗎?
可以,在 Debian 等標準建置中可以修正。ncurses 會先搜尋 $HOME/.terminfo,再搜尋任何系統目錄;只有在伺服器上設定的 $TERMINFO 變數會更早檢查。因此,在一般情況下,將項目放在該位置就足以供你的帳號使用。ncurses 對家目錄的查詢是選用功能,所以後面的 tput longname 檢查很重要。每台伺服器執行一次 infocmp -x | ssh user@host -- tic -x -。無法寫入系統路徑時,tic 會寫入你的家目錄;對無特權帳號而言,這是正常情況。登入後執行 tput longname,確認查詢現在可以解析該項目。
為主機設定 TERM=xterm-256color 會失去哪些功能?
你的終端機模擬器所描述、超出 xterm-256color 項目的所有功能,例如透過 RGB 提供的 24 位元色彩,以及透過 Smulx 提供的樣式底線。依賴 terminfo 項目的程式看不到這些功能,因此會使用最接近的替代設定,除非你另外進行設定,例如 Vim 的 termguicolors 選項對色彩的處理。功能鍵的控制序列也可能與實際終端機不同。請在用戶端的 ~/.ssh/config 中設定該值,不要在伺服器的 .bashrc 中設定,否則已能正常運作的終端機所建立的工作階段也會被降級。
為什麼執行 sudo -i 後錯誤又出現?
sudo -i 會使用 HOME=/root 以 root 身分啟動 login shell,同時保留你的 TERM 值。ncurses 接著會搜尋 /root/.terminfo,而不是你自己的家目錄,結果找不到項目,因此 root 會看到與你的帳號先前不同的相同錯誤。執行 sudo -i env,並檢查 HOME 與 TERM 行。使用 sudo tic -x -o /usr/share/terminfo 將項目編譯到系統目錄。放在 /root/.terminfo 中的副本也可能有效,但 ncurses 可能會限制特權程序對家目錄的查詢,因此請以 root 身分使用 tput longname 確認。
apt install ncurses-term 一定能修正問題嗎?
不一定。它只會加入你所使用發行版封裝的 ncurses 版本中已存在的項目。Ubuntu 24.04 隨附 ncurses 6.4(截至 November 2026 為 ncurses-bin 6.4+20240113-1ubuntu2.2),而 Ghostty 的項目是在 ncurses 6.5-20241228 的上游版本中加入,因此該套件不可能包含這個項目。依賴該套件前,先使用 tput -T <name> longname 檢查;如果檢查結果仍顯示 unknown terminal,請自行提供該項目。