SSH报错unknown terminal type怎么修复
SSH中的TERM名称若不在服务器terminfo数据库中,curses程序会报unknown terminal type并退出。将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 构建;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" 有输出,则会先检查该位置;如果其中存在同名条目,它会优先于您的条目。
修复 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 或更高版本,该版本于 2021 年 8 月发布。较旧的客户端无论是否存在此行,都会发送终端模拟器自身的 TERM。TERM 是唯一不需要服务器许可的变量:手册中写道:“与 SendEnv 类似,但 TERM 变量除外,服务器必须准备好接受该环境变量。”因此,即使连接的是完全加固、没有任何 AcceptEnv 行的 sshd,此方法也能正常工作。
代价是:终端模拟器所描述的、超出纯 xterm-256color 的所有功能都会丢失。这包括通过 RGB capability 声明的 24 位颜色,以及通过 Smulx 实现的样式下划线。依赖 terminfo 条目的程序将无法再看到这些功能,因此会退回到 256 色和普通下划线,除非您配置它们继续发送相应的控制序列。例如,Vim 仍可通过 set termguicolors 绘制 24 位颜色,因为其内置的 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(截至 November 2026)。Ghostty 条目是在上游 ncurses 6.5-20241228 中加入的,版本更新,因此 Ubuntu 24.04 中的 apt install ncurses-term 无论运行多少次,都无法生成 xterm-ghostty 条目。tput -T <name> longname 用于检查:条目存在时,它会打印描述;条目不存在时,它会以退出状态 3 停止,并显示 unknown terminal。
如果不想安装整个软件包,而只想系统范围内安装单个条目,请将源文件复制到服务器,并以 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 集成功能(ssh-env 和 ssh-terminfo),可自动执行这两项修复。Ghostty 1.4.0 于 October 27, 2026 发布,新增了 1.3.x 版本没有的 ghostty +ssh 包装器;现在,这两个可选功能都会调用它。连接前,它会将 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 的值,因为该协议会在伪终端请求中携带这个名称。远程 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 身份启动登录 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 检查;如果检查结果仍为未知终端,请自行提供该条目。