mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
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
@@ -5,6 +5,12 @@ All notable changes to CC Switch will be documented in this file.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Linux Wayland: Override the AppImage's Forced `GDK_BACKEND=x11`**: The AppImage's GTK launch hook (`linuxdeploy-plugin-gtk.sh`) unconditionally exports `GDK_BACKEND=x11` to dodge a historical native-Wayland crash (tauri-apps/tauri#8541). On newer Wayland + NVIDIA setups this forced XWayland leaves the WebKitGTK web content unable to receive pointer events — the GTK title bar stays clickable but the page is dead — and black-screens on resize; the existing `WEBKIT_DISABLE_*` mitigations don't help because the root cause is the forced window backend, not rendering. Since the hook also overrides any user-set `GDK_BACKEND`, there was no way to switch back without unpacking the AppImage. `main.rs` now reads an opt-in `CC_SWITCH_GDK_BACKEND` escape hatch (which the hook never touches) before GTK init: leaving it unset keeps the current x11 behavior unchanged (zero regression), while `CC_SWITCH_GDK_BACKEND=wayland` forces native Wayland. The override is generic, so users on tiling Wayland compositors hitting the inverse input bug can set `CC_SWITCH_GDK_BACKEND=x11`. (#4351, fixes #4350)
|
||||
|
||||
## [3.16.4] - 2026-06-27
|
||||
|
||||
Development since v3.16.3 focuses on tightening the Codex proxy path — native OpenAI Responses migration for the major Chinese providers, a decoupled upstream-format selector, zstd request/error-body decompression, and a run of tool-call and OAuth-over-proxy fixes — alongside richer usage and pricing tooling (models.dev pricing import, Volcengine Ark coding/agent-plan quotas, live-tracking date ranges, GLM-5.2/Doubao Seed 2.1 pricing), new proxy and resilience capabilities (custom request header/body overrides, an in-app recovery screen for too-new databases, native Windows ARM64 builds), and a broad wave of preset and branding updates (the SubRouter and OpenCode Go subscriptions, the CTok→ETok rename, Kimi rebranding and prime-partner badges, and a Kimi K2.7 Code sponsor banner).
|
||||
|
||||
@@ -284,6 +284,19 @@ Add an official provider from the preset list. After switching to it, run the Lo
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux (Wayland + NVIDIA): clicks don't register and the window black-screens on resize</strong></summary>
|
||||
|
||||
The AppImage forces `GDK_BACKEND=x11` (XWayland) to avoid a historical native-Wayland crash. On newer Wayland + NVIDIA setups this can leave the web content area unclickable (the title-bar buttons still work) and black-screen on resize. Launch with the opt-in escape hatch to switch back to native Wayland:
|
||||
|
||||
```bash
|
||||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||||
```
|
||||
|
||||
If you launch 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. The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, try `CC_SWITCH_GDK_BACKEND=x11` instead. Leaving it unset keeps the default behavior.
|
||||
|
||||
</details>
|
||||
|
||||
## Documentation
|
||||
|
||||
For detailed guides on every feature, check out the **[User Manual](docs/user-manual/en/README.md)** — covering provider management, MCP/Prompts/Skills, proxy & failover, and more.
|
||||
|
||||
@@ -284,6 +284,19 @@ Fügen Sie einen offiziellen Anbieter aus der Preset-Liste hinzu. Führen Sie na
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux (Wayland + NVIDIA): Klicks im Webinhalt reagieren nicht, schwarzer Bildschirm beim Größenändern</strong></summary>
|
||||
|
||||
Das AppImage erzwingt `GDK_BACKEND=x11` (XWayland), um einen historischen nativen Wayland-Absturz zu vermeiden. Auf neueren Wayland-+-NVIDIA-Systemen kann das dazu führen, dass der Webinhalt nicht anklickbar ist (die Titelleisten-Schaltflächen funktionieren weiterhin) und das Fenster beim Größenändern schwarz wird. Starten Sie mit dem optionalen Notausgang, um zu nativem Wayland zu wechseln:
|
||||
|
||||
```bash
|
||||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||||
```
|
||||
|
||||
Wenn Sie über ein Desktop-Symbol starten, fügen Sie es der `Exec=`-Zeile der `.desktop`-Datei hinzu (z. B. `env CC_SWITCH_GDK_BACKEND=wayland /pfad/zum/AppImage`) oder setzen Sie es in Ihrer Sitzungsumgebung. Die Variable ist generisch: Auf Tiling-Wayland-Compositors (sway/Hyprland), bei denen Klicks nicht reagieren, versuchen Sie umgekehrt `CC_SWITCH_GDK_BACKEND=x11`. Bleibt sie ungesetzt, bleibt das Standardverhalten erhalten.
|
||||
|
||||
</details>
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Ausführliche Anleitungen zu jeder Funktion finden Sie im **[Benutzerhandbuch](docs/user-manual/en/README.md)** — es deckt Anbieterverwaltung, MCP/Prompts/Skills, Proxy & Failover und mehr ab.
|
||||
|
||||
@@ -284,6 +284,19 @@ CC Switch は「最小限の介入」という設計原則に従っています
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux（Wayland + NVIDIA）：Web コンテンツがクリックできない・リサイズで黒画面になる</strong></summary>
|
||||
|
||||
AppImage は過去のネイティブ Wayland クラッシュを避けるため `GDK_BACKEND=x11`（XWayland）を強制します。新しい Wayland + NVIDIA 環境ではこれが原因で Web コンテンツ領域がクリックできなくなり（タイトルバーのボタンは動作します）、リサイズ時に黒画面になることがあります。内蔵のエスケープハッチでネイティブ Wayland に戻せます：
|
||||
|
||||
```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` を試してください。未設定の場合は既定の動作のままです。
|
||||
|
||||
</details>
|
||||
|
||||
## ドキュメント
|
||||
|
||||
各機能の詳しい使い方については、**[ユーザーマニュアル](docs/user-manual/ja/README.md)** をご覧ください。プロバイダ管理、MCP/Prompts/Skills、プロキシとフェイルオーバーなど、すべての機能を網羅しています。
|
||||
|
||||
@@ -287,6 +287,19 @@ CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接下载安
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux（Wayland + 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、代理与故障转移等全部功能。
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 のまま）で、副作用はありません。
|
||||
|
||||
## プロバイダーに関する問題
|
||||
|
||||
### プロバイダーを切り替えても反映されない
|
||||
|
||||
@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
|
||||
./CC-Switch-*.AppImage --no-sandbox
|
||||
```
|
||||
|
||||
### Linux 点击无响应 / 缩放后黑屏（Wayland + NVIDIA）
|
||||
|
||||
**问题**：主界面网页内容区完全点不动（标题栏的最小化/最大化/关闭仍可点），窗口缩放或最大化-还原后黑屏。常见于 Wayland 会话 + NVIDIA 显卡。
|
||||
|
||||
**原因**：AppImage 的 GTK 启动钩子会无条件强制 `GDK_BACKEND=x11`（走 XWayland）以规避历史上的原生 Wayland 崩溃；但在较新的 Wayland + NVIDIA 环境下，强制 XWayland 反而使 WebKitGTK 的网页内容收不到指针事件。现有的 `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`），或在会话环境中设置，否则图标启动读不到该变量。
|
||||
- 该变量是通用的：在 tiling Wayland 合成器（sway/Hyprland）下若反而出现点击失效，可设 `CC_SWITCH_GDK_BACKEND=x11`。
|
||||
- 不设置时行为与现状完全一致（仍走 x11），无副作用。
|
||||
|
||||
## 供应商问题
|
||||
|
||||
### 切换供应商后不生效
|
||||
|
||||
Reference in New Issue
Block a user