Pebrel 文档

文档 / 参考与帮助

故障排查

处理启动、字体、SSH、文件保存和会话恢复中的常见问题。

应用打不开或没有窗口

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

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

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

新终端立即退出

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

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

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

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

只有背景影响阅读时,先关闭图片和模糊、提高不透明度。详细步骤见字体。

SSH 连接超时

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

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

SSH 认证失败或指纹变化

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

指纹变化先向管理员确认,不要直接接受以跳过错误。详见SSH 认证。

文件树没有跟随当前目录

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

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

SFTP 上传或下载失败

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

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

文档无法编辑或保存

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

保存冲突先复制未保存内容,再重新读取并比较。远端保存失败还需检查服务器权限与网络,见远端编辑。

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

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

历史恢复需要对应工具的会话记录和有效身份。右键标签使用重试或选择会话入口,或在 CLI 自己的历史里查找,见AI 会话历史。

设置改了却没有效果

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

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

更新后还是旧版本

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

提交问题反馈

打开 设置 → 应用 → 反馈问题,提供下面的信息:

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

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

关于本页

内容来自用户指南 PR #291,原始基线 v2.1.1。部分功能和界面可能随版本变化,请同时参考发行说明。

Markdown 原文 ↓发行说明 ↗
核对来源

搜索文档

输入关键词,搜索使用指南。

本地全文搜索 PAGEFIND / 不上传搜索内容