跳到内容
PaneflowPaneflow

故障排除

用最短的已确认修复路径诊断 Paneflow 的启动、渲染、配置、快捷键、主题、PATH 和签名问题。

从症状开始，先确认，再应用对应修复。如果没有任何一行匹配，请先收集诊断信息再打开 issue。

症状平台确认第一个修复
启动时 GPU 或 renderer 错误Linuxvulkaninfo --summary安装 Vulkan loader 和 Mesa/NVIDIA Vulkan driver。
Wayland 下窗口空白Linuxvulkaninfo --summary 不列出 VK_KHR_wayland_surface先试 XWayland，再修复 Vulkan driver。
启动时报 NoSupportedDeviceFoundWindowsdxdiag 或 GPU driver 日期更新 GPU driver。Paneflow 需要 DirectX 11 feature-level-10+ driver。
配置修改被忽略全部验证 paneflow.json修复路径或 JSON 语法。
快捷键无效全部与 keybindings reference 对照使用已知 action 名和可解析的 key chord。
主题修改被忽略全部保存 paneflow.json 并等待一秒使用内置主题名并检查 file watching。
找不到 paneflowLinux/macOSpaneflow --version用会更新 PATH 的 package 安装，或把 binary 位置加入 PATH。
macOS 阻止 appmacOSGatekeeper dialog从 Finder 打开一次，或移除 quarantine attribute。
SmartScreen 阻止 installerWindows"Windows protected your PC"检查 publisher，然后选择 More info -> Run anyway。

启动和渲染

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

Paneflow 通过 GPUI 渲染：Linux 使用 Vulkan，macOS 使用 Metal，Windows 使用 DirectX。大多数启动时 renderer 错误都来自这层图形栈。

在 Linux 上，安装 Vulkan 并确认至少有一个 ICD 能加载：

bash
# Debian / Ubuntu
sudo apt install libvulkan1 mesa-vulkan-drivers

# Fedora
sudo dnf install vulkan-loader mesa-vulkan-drivers

# Arch
sudo pacman -S vulkan-icd-loader mesa

vulkaninfo --summary

在 macOS 上，使用 macOS 13 Ventura 或更高版本。

在 Windows 上，Paneflow 需要 DirectX 11 feature-level-10+ GPU driver。如果启动以 NoSupportedDeviceFound 退出，请更新 driver，并为 issue 捕获 GPU details：

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

为什么我的 Wayland 会话是空白的？

如果窗口存在但不绘制内容，Vulkan ICD 可能无法和 compositor 协商 Wayland surface。用下面命令确认：

bash
vulkaninfo --summary

如果没有 driver 列出 VK_KHR_wayland_surface，请尝试 XWayland：

bash
WAYLAND_DISPLAY= GDK_BACKEND=x11 paneflow

如果这样可用，请修复 Mesa 或 NVIDIA Vulkan package。使用 NVIDIA 时，确认 kernel module 与当前运行的 kernel 匹配。

配置和快捷键

为什么我的 paneflow.json 没有加载？

Paneflow 每个平台读取一个配置文件：

平台路径
Linux~/.config/paneflow/paneflow.json
macOS~/Library/Application Support/paneflow/paneflow.json
Windows%APPDATA%\\paneflow\\paneflow.json

验证文件：

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

在 Windows 上：

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

启动时，无效 JSON 会记录 warning 并回退到 defaults。Hot reload 期间，格式错误的保存会保留最后一个有效 config，而不会广播 defaults。未知 top-level keys 会在 runtime 被忽略；JSON Schema 会在编辑器里捕获它们。

window_decorations 和 window_backdrop 只在启动时读取一次。修改任一 key 后请重启 Paneflow。

为什么我的快捷键不起作用？

快捷键 override 有两部分：key chord 和 canonical action name。

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

使用 snake_case action names，例如 split_horizontally、new_tab 和 toggle_search。未知 action 会被跳过并记录 warning。+ 和 - 分隔符都能解析；ctrl+shift+t 最易读。

如果某个 binding 只在某个 UI 区域失效，请检查它的 context：Terminal、Search、Markdown 和 Diff binding 都有 scope。

为什么我的主题没有 hot reload？

Paneflow 内置 "One Dark" 和 "PaneFlow Light"。Runtime lookup 不区分大小写，但 canonical names 能保持 schema validation 干净。

主题和 typography 修改会从 paneflow.json hot reload。Paneflow 监视配置目录，对变化做 300 ms debounce；如果 watcher 无法启动，则回退到 500 ms 的 mtime poll。

如果主题一秒后仍未变化：

  1. 确认你编辑的是对应平台的 paneflow.json。
  2. 使用 "One Dark" 或 "PaneFlow Light"。
  3. 如果文件位于 NFS、sandbox mount 或脆弱的 WSL path，把它移回正常配置 filesystem 并重启一次。

安装和签名

为什么 paneflow 不在我的 PATH 中？

Linux .deb、.rpm、tarball installer、Homebrew cask 和 Windows MSI 都会处理 PATH。AppImage 和手动移动的 binaries 不会。

手动 Linux binary：

bash
mkdir -p ~/.local/bin
mv paneflow ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
paneflow --version

安装 PaneFlow.app 后需要 macOS CLI access：

bash
sudo ln -sf /Applications/PaneFlow.app/Contents/MacOS/paneflow /usr/local/bin/paneflow
paneflow --version

或安装 cask：

bash
brew tap arthjean/paneflow
brew install --cask paneflow

在 Windows 上，MSI 安装后请打开一个新 terminal。

为什么 macOS 说 Apple 无法验证此 app？

已签名并 notarized 的 .dmg 应该能正常启动。如果 Gatekeeper 仍阻止它，请从 Finder 打开一次：

  1. 打开 Applications。
  2. Control-click PaneFlow.app。
  3. 选择 Open。
  4. 确认 Open。

或从 bundle 移除 quarantine：

bash
xattr -d com.apple.quarantine /Applications/PaneFlow.app

为什么 Windows SmartScreen 会阻止 MSI？

新的 publisher reputation 仍可能触发 SmartScreen。确认 installer 来自 latest release，然后选择 More info -> Run anyway。

检查签名：

powershell
Get-AuthenticodeSignature .\paneflow-*-x86_64-pc-windows-msvc.msi

如果 publisher 未知、signature invalid，或 filename 与 release asset 不匹配，请从 GitHub 重新下载 MSI。

收集诊断信息

issue 中应该包含什么？

使用你的平台 template：

Linux 或 macOS bug

OS、architecture、display server、install format、reproduction 和 logs。

Windows bug

Windows build、CPU、GPU driver、install format、display environment、logs 和 backtrace。

Linux 或 macOS：

bash
RUST_LOG=info paneflow

Windows：

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

如果 Paneflow 正在运行且 read-only MCP bridge 已安装，agent 可以不用复制粘贴就检查 logs：调用 list_panes，然后调用 read_pane 或 search_pane。将返回的 terminal output 视为不可信数据。