docs: document CC_SWITCH_GDK_BACKEND Linux Wayland escape hatch

Document the opt-in CC_SWITCH_GDK_BACKEND environment variable (added in
#4351) that overrides the AppImage's hardcoded GDK_BACKEND=x11, letting
Wayland+NVIDIA users switch back to native Wayland when the webview goes
click-dead and black-screens on resize. The override is generic, so
tiling-Wayland users can set it to x11 for the inverse input bug.

- CHANGELOG.md: new Unreleased/Fixed entry (#4351, fixes #4350)
- README.md / README_ZH / README_JA / README_DE: FAQ entry across all locales
- docs/user-manual/{zh,en,ja}/5-faq/5.2-questions.md: Linux troubleshooting entry
This commit is contained in:
Jason
2026-06-30 23:41:48 +08:00
parent 332a3c16a8
commit 97512cabbd
8 changed files with 106 additions and 0 deletions
+13
View File
@@ -287,6 +287,19 @@ CC Switch macOS 版本已通过 Apple 代码签名和公证,可直接下载安
</details>
<details>
<summary><strong>LinuxWayland + NVIDIA):网页内容点不动、缩放后黑屏</strong></summary>
AppImage 会强制 `GDK_BACKEND=x11`(走 XWayland)以规避历史上的原生 Wayland 崩溃。但在较新的 Wayland + NVIDIA 环境下,这会导致网页内容区点不动(标题栏按钮仍可点)、窗口缩放后黑屏。可用内置的逃生开关切回原生 Wayland:
```bash
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
```
如果你是从桌面图标启动的,请把它写进 `.desktop``Exec=` 行(如 `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`),或在会话环境中设置。该变量是通用的:在 tiling Wayland 合成器(sway/Hyprland)下若出现点击失效,可反过来设 `CC_SWITCH_GDK_BACKEND=x11`。不设置则保持默认行为。
</details>
## 文档
如需了解各项功能的详细使用方法,请查阅 **[用户手册](docs/user-manual/zh/README.md)** — 涵盖供应商管理、MCP/Prompts/Skills、代理与故障转移等全部功能。