跳到内容
PaneflowPaneflow
文档

故障排除

排查 Paneflow 启动、渲染、配置、快捷键、主题、PATH 和签名问题。按症状检查，并收集问题报告所需的信息。

找到对应症状，按步骤检查。每次只修改一项，便于判断哪一步有效。 如果问题持续，按页面末尾的说明收集诊断信息。

症状平台首先检查
启动时 GPU 或渲染错误Linux检查 Vulkan 支持和显卡驱动。
Wayland 下窗口空白Linux比较 Wayland 和 XWayland 的启动结果。
启动时报 NoSupportedDeviceFoundWindows更新 GPU 驱动并记录版本。
配置修改未生效全部检查文件路径、JSON 语法和设置类型。
快捷键无效全部检查操作名和应用中获得焦点的区域。
主题修改未生效全部检查主题名称并保存配置。
找不到 paneflow 命令全部按安装方式检查 PATH。
Gatekeeper 阻止应用macOS检查下载来源和准确的警告内容。
SmartScreen 阻止 MSIWindows验证安装程序签名和发布者。

启动和渲染

为什么 Paneflow 会出现 GPU 或渲染错误？

Linux： Paneflow 需要图形会话和支持 Vulkan 的 GPU 驱动。 在该会话的终端中运行：

bash
vulkaninfo --summary

如果找不到 vulkaninfo，使用发行版的包管理器安装 vulkan-tools。 缺少诊断工具不代表 Vulkan 不可用。

如果命令失败或未列出 GPU，检查 Vulkan 加载器和驱动。加载器软件包在 Debian/Ubuntu 上为 libvulkan1，Fedora 上为 vulkan-loader， Arch 上为 vulkan-icd-loader。安装适合 GPU 的 Vulkan 驱动： 受支持的 Intel/AMD GPU 使用 Mesa，NVIDIA 使用对应驱动。 重新启动 Paneflow；如果错误持续，保留错误内容用于报告。

macOS： 确认使用 Apple Silicon Mac 和 macOS 13 Ventura 或更高版本。 更新 macOS 后重试。参见 macOS 安装要求。

Windows： 遇到 NoSupportedDeviceFound 时，从 PC 或 GPU 厂商获取 新版驱动，然后重新启动 Paneflow。驱动须支持 DirectX 11 功能级别 10 或更高。记录 GPU 和驱动信息：

powershell
Get-CimInstance Win32_VideoController |
  Select-Object Name, DriverVersion, DriverDate

为什么 Wayland 会话中的窗口是空白的？

窗口空白可能与显卡驱动或显示服务器有关，单凭这一症状无法确定原因。 按上方说明检查 Vulkan，然后退出 Paneflow，在同一图形会话中尝试 XWayland：

bash
env -u WAYLAND_DISPLAY paneflow

这需要 XWayland 和有效的 DISPLAY 变量。命令仅为本次启动选择 X11。 如果可以打开，可暂时采用这一方式，检查显卡驱动更新，并在问题报告中 提供两种启动方式的结果。

配置和快捷键

为什么 paneflow.json 没有加载？

确认编辑的是运行中应用使用的配置。发布版本默认使用以下路径：

平台路径
Linux 和 macOS~/.paneflow/paneflow.json
Windows%USERPROFILE%\.paneflow\paneflow.json

PANEFLOW_HOME 中的绝对路径会更改此目录。如果设置了该变量， 相应修改以下命令中的路径。

Linux 或 macOS，需已安装 Python 3：

bash
python3 -m json.tool ~/.paneflow/paneflow.json

Windows：

powershell
Get-Content $env:USERPROFILE\.paneflow\paneflow.json -Raw |
  ConvertFrom-Json | Out-Null

修复报告的语法错误，保存文件后重试。文件不存在时使用默认值。 启动时配置无效也会使用默认值；运行中保存无效配置则保留上一次有效配置。

这些命令只检查 JSON 语法。使用 配置架构参考 检查设置名、类型和允许的值。应用忽略顶层未知键，因此拼写错误可能 表现为设置未生效。

修改 window_decorations 或 window_backdrop 后需要重新启动。

为什么快捷键不起作用？

shortcuts 中的每个条目将按键组合映射到操作名。例如，以下条目用 ctrl+shift+t 创建标签页，并禁用 ctrl+shift+w。 将这些条目加入现有配置：

json
{
  "shortcuts": {
    "ctrl+shift+t": "new_tab",
    "ctrl+shift+w": "none"
  }
}

使用 键盘快捷键参考 中的操作名，例如 new_tab、 split_horizontally 或 toggle_search。未知操作会被跳过并记录警告。

如果快捷键只在某一区域失效，检查哪个视图获得了焦点。 Terminal、Search、Markdown 和 Diff 操作各有适用范围。

为什么主题没有自动重新加载？

在顶层 theme 中使用 "One Dark" 或 "PaneFlow Light"。 参见 主题设置和示例。

  1. 检查上方配置路径，包括 PANEFLOW_HOME 设置。
  2. 检查 JSON 语法和主题名称，然后保存文件。
  3. 稍等片刻。如果仍未生效，重新启动 Paneflow。
  4. 如果重启后生效，但保存时不生效，请报告问题，并说明文件是否 位于网络驱动器或挂载的文件系统中。

安装和签名

为什么 paneflow 不在 PATH 中？

解决方式取决于安装方法：

  • Linux： .deb 和 .rpm 将命令安装到系统目录。AppImage 和 .tar.gz 安装可能需要将 ~/.local/bin 加入 PATH。 按照 Linux 命令与 PATH 说明 操作。
  • macOS： 通过 Homebrew 或 DMG 安装 PaneFlow.app 不会自动 将可执行文件加入 shell 的 PATH。按照 macOS 终端访问说明 操作。
  • Windows： MSI 安装后，关闭终端窗口并从开始菜单重新打开 PowerShell。 如果仍找不到命令，按照 Windows 命令检查步骤 操作。

为什么 macOS 提示 Apple 无法验证应用？

官方 DMG 已签名并经过公证。重新下载 Paneflow 最新版本， 核对警告的准确内容。按照 macOS Gatekeeper 步骤 操作，其中区分了首次启动确认和应用被阻止的情况。 如果警告提示应用损坏或会损害电脑，保持阻止状态并报告准确的消息。

为什么 Windows SmartScreen 会阻止 MSI？

签名安装程序仍可能触发 SmartScreen 信誉警告。继续前先按 Windows 签名验证步骤 操作。 确认签名为 Valid，发布者为 Strivex。如果任一项不符，从官方版本 重新下载 MSI。如果组织策略阻止安装，联系管理员。

收集诊断信息

问题报告应包含什么？

如果应用可以打开，选择 Help > System Info，然后选择 Copy。 附上该信息块、使用的 shell、准确的错误消息、复现步骤和预期结果， 并说明已尝试本页中的哪些检查。

如果应用无法打开，手动提供 Paneflow 版本、操作系统版本、处理器架构、 安装格式、GPU 和驱动信息。在 Windows 上，winver 可显示版本和内部版本号。

使用适合平台的报告表单：

报告 Linux 或 macOS 问题版本、显示服务器、GPU、复现步骤和应用输出。报告 Windows 问题Windows 内部版本、GPU 驱动、shell、复现步骤和应用输出。

收集应用输出前，先退出 Paneflow，再从终端启用日志并启动。 Linux 或 macOS：

bash
RUST_LOG=info paneflow

Windows，使用 MSI 默认安装目录时：

powershell
$env:RUST_LOG = "info"
$env:RUST_BACKTRACE = "1"
& "$env:ProgramFiles\PaneFlow\paneflow.exe"

如果找不到命令或可执行文件，先参阅 PATH 说明，或使用安装文件的完整路径。 对于 macOS DMG 安装，将 paneflow 替换为 /Applications/PaneFlow.app/Contents/MacOS/paneflow。

复现问题，并将相关终端输出复制到报告中。发布前移除访问令牌、 私有路径或项目内容。

只读 MCP 桥接 读取面板输出。启动、配置或渲染问题 需要使用上方命令收集应用日志。