admin/CC-Switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-07-24 12:44:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document CC_SWITCH_GDK_BACKEND Linux Wayland escape hatch

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-manual/en/5-faq/5.2-questions.md
+16
View File
@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage --no-sandbox
```
### Linux: Clicks Don't Register / Black Screen on Resize (Wayland + NVIDIA)
**Problem**: The web content area is completely unclickable (the title-bar minimize/maximize/close buttons still work), and the window black-screens on resize or maximize-restore. Common on Wayland sessions with an NVIDIA GPU.
**Cause**: The AppImage's GTK launch hook unconditionally forces `GDK_BACKEND=x11` (XWayland) to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, forced XWayland leaves the WebKitGTK web content unable to receive pointer events. The existing `WEBKIT_DISABLE_*` mitigations don't help here because the root cause is the forced window backend, not rendering.
**Solution**: Use the dedicated `CC_SWITCH_GDK_BACKEND` environment variable to switch back to native Wayland (it is read before GTK init, and the hook never overrides it):
```bash
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
```
- When launching from a desktop icon, add it to the `.desktop` `Exec=` line (e.g. `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`) or set it in your session environment — otherwise an icon launch won't see the variable.
- The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, set `CC_SWITCH_GDK_BACKEND=x11` instead.
- Leaving it unset behaves exactly as before (still x11), with no side effects.
## Provider Issues
### Provider Switch Doesn't Take Effect