# 故障排查

## 应用打不开或没有窗口

先确认安装包与系统、处理器匹配，并已完整解压。Windows 便携版保留整个目录；macOS 从 Applications 启动，不从 DMG 内直接运行；Linux TAR.GZ 使用包内 `AppRun`。

开启过 **静默启动**或 **关窗后保留后台会话**时，窗口可能只是隐藏了，先检查系统托盘（macOS 为菜单栏）。macOS 被系统阻止时，按[首次启动说明](/docs/installation/)处理。

仍无法启动时，从系统终端运行对应程序并保留错误输出，不要先删除所有个人数据。

## 新终端立即退出

先从系统终端运行同一 Shell，确认它本身可以启动。再检查 **设置 → 终端 → 默认 Shell**与启动目录。

自定义 Profile 的 `command`只填写程序，参数放在 `args`。WSL 先用 `wsl -d 发行版名称`检查发行版是否可启动。修改后新建标签测试。

## 字体缺字、箭头变成方框或列不齐

恢复默认终端字体和字号，再检查 **中文终端字体**、**字体间距**与 **字体连字**。Powerline 箭头需要字体提供相应字形。

只有背景影响阅读时，先关闭图片和模糊、提高不透明度。详细步骤见[字体](/docs/fonts/)。

## SSH 连接超时

检查服务器地址、端口、VPN 和本地网络。需要代理或跳板时，编辑主机的 **高级**页，查看连接规则预览。

先测试第一跳，再检查跳板到目标的连通性。端口可达后仍认证失败，转到下一项，不必反复更换终端字体或 Shell。

## SSH 认证失败或指纹变化

核对用户名，确认选择了服务器允许的认证方式。私钥认证选择私钥而非 `.pub`文件，密钥口令与账户密码分开输入；需要验证码时选择交互式认证。

指纹变化先向管理员确认，不要直接接受以跳过错误。详见[SSH 认证](/docs/ssh-auth/)。

## 文件树没有跟随当前目录

先在终端运行 `pwd`（cmd 使用 `cd`）确认位置，再点击 **跟随当前终端并刷新**。手动进入其他目录后，需要通过跟随入口回到终端位置。

仍不更新时，检查当前 Shell 的目录上报是否可用。SSH 文件列表使用 **重新跟随**和 **重新读取**。

## SFTP 上传或下载失败

查看目标路径，检查源文件读取权限、目标写入权限、磁盘空间与 SSH 连接。目标在文件选择期间发生变化时，回到正确目录重新发起传输。

有同名冲突时明确选择覆盖、跳过或保留两者。取消之后检查哪些文件已完成，再重新传输，见[SFTP](/docs/sftp/)。

## 文档无法编辑或保存

本地 Markdown 先使用 **文档操作 → 源码**；阅读视图不能直接编辑段落。超过 8 MB 或非完整 UTF-8 文本可能只读，需要外部编辑器。

保存冲突先复制未保存内容，再重新读取并比较。远端保存失败还需检查服务器权限与网络，见[远端编辑](/docs/remote-edit/)。

## AI 图标、活动状态或历史缺失

先在同一终端检查 CLI 是否可运行。启用或更改 Agent 集成后重启 CLI；工具状态异常时刷新 **设置 → Agents**并检查集成结果。

历史恢复需要对应工具的会话记录和有效身份。右键标签使用重试或选择会话入口，或在 CLI 自己的历史里查找，见[AI 会话历史](/docs/ai-history/)。

## 设置改了却没有效果

先确认修改的是正确设置：界面字号与终端字号分开，背景图片不透明度与终端不透明度分开，网络代理与新终端系统代理开关分开。

Shell、回滚行数和进程环境需在新建窗格中验证。Lua 配置报错时运行 `pebrel config check`；存在 GUI 覆盖项时检查 **设置**中的当前值。

## 更新后还是旧版本

完全退出后台实例，检查快捷方式是否仍指向旧目录。便携版应从新解压目录启动，macOS 应从替换后的 Applications 应用启动，再检查 **设置 → 应用**的版本号。

## 提交问题反馈

打开 **设置 → 应用 → 反馈问题**，提供下面的信息：

```text
Pebrel 版本：
系统和处理器架构：
安装方式：安装程序 / ZIP / DMG / DEB / AppImage / TAR.GZ
Shell 或远端环境：
操作步骤：
预期结果：
实际结果和错误文字：
是否能稳定重现：
```

附上能说明问题的截图或脱敏日志。不要附上密码、Token、私钥或运行时发现文件。涉及主题、字体或缩放时，再补充对应设置。

---
Source: Kuddev/pebrel PR #291, WilliamWang1721 and Pebrel contributors.
Adapted for pebrel.com. License: GPL-3.0.
