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
@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage --no-sandbox
```
### Linux:クリックが効かない / リサイズで黒画面(Wayland + NVIDIA
**問題**:Web コンテンツ領域がまったくクリックできません(タイトルバーの最小化/最大化/閉じるボタンは動作します)。ウィンドウのリサイズや最大化-復元後に黒画面になります。Wayland セッション + NVIDIA GPU でよく発生します。
**原因**AppImage の GTK 起動フックが、過去のネイティブ Wayland クラッシュを避けるために `GDK_BACKEND=x11`(XWayland)を無条件で強制します。新しい Wayland + NVIDIA 環境では、強制された XWayland によって WebKitGTK の Web コンテンツがポインタイベントを受け取れなくなります。既存の `WEBKIT_DISABLE_*` の緩和策は、根本原因が強制されたウィンドウバックエンドであり描画ではないため、ここでは効きません。
**解決方法**:専用の環境変数 `CC_SWITCH_GDK_BACKEND` でネイティブ Wayland に戻します(GTK 初期化前に読み取られ、フックが上書きしません):
```bash
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
```
- デスクトップアイコンから起動する場合は、`.desktop``Exec=` 行に追記するか(例:`env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`)、セッション環境で設定してください。そうしないとアイコン起動では変数が読み取られません。
- この変数は汎用です:タイル型 Wayland コンポジタ(sway/Hyprland)でクリックが効かない場合は、`CC_SWITCH_GDK_BACKEND=x11` を設定してください。
- 未設定の場合は現状とまったく同じ動作(x11 のまま)で、副作用はありません。
## プロバイダーに関する問題
### プロバイダーを切り替えても反映されない