故障排除与常见问题

如果您在使用 PhanTerm 时遇到了问题，请参考以下常见问题排查指南。

1. 终端渲染或文字重叠问题

现象：进入终端后，某些复杂的命令行应用（如带长命令自动折行的应用、多重色彩的 Git 日志）出现显示错位、文字残影或光标位置错误。

排查方案： 这通常是由于操作系统检测到的终端长宽维度不同步造成的。请尝试手动拖拽调整一下窗口大小。PhanTerm 的监听层在接收到窗口变化（Resize）事件后，会向远程 PTY 强制下发一次正确的维度重置，这能解决 90% 以上的画面错乱问题。

2. 无法连接到服务器 (Connection Timed Out)

现象：一直显示 Connecting... 的转圈动画，随后抛出超时或网络不可达的提示。

排查方案：

1. 请先检查您填写的 IP 和端口（尤其是非 22 的自定义端口）是否正确。
2. 确认远程机器的防火墙或云服务商安全组已放行您的本地公网 IP。
3. 如果目标服务器位于内网环境，您可能需要在连接设置中配置跳板机 (ProxyJump) 进行穿透。

3. SSH 密钥认证被拒绝 (Permission Denied)

现象：已配置密钥认证，但仍然提示输入密码或连接失败。

排查方案：

1. 核对路径：检查您填写的 IdentityFile 路径是否存在且有效。
2. 格式检查：确保您提供的是私钥文件（如 id_rsa 或 id_ed25519），而不是 .pub 后缀的公钥文件。
3. 系统 Agent：如果您选择了依赖系统的 ssh-agent 或 Pageant 进行管理，请确保这些后台服务正在运行，且您的密钥已经通过 ssh-add 被正确加载到系统中。

4. 主机密钥指纹不匹配红屏警告

现象：连接时弹出强烈的红色警告弹窗，提示主机密钥签名有误。

排查方案： 不要轻易放行！请先联系您的服务器管理员。只有在以下两种情况下您才应该认为这是正常的：

1. 操作系统刚被重装。
2. 管理员告知您刚刚轮换了 SSH 安全证书。

若确认安全，您可以进入本地配置目录（参考配置参考），在 known_hosts.yaml 中手动删去对应冲突的那行记录后重试。