vanloctech · Sep 20, 2026 · Sep 20, 2026 · Sep 20, 2026 · chatgpt-codex-connector · Sep 20, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -238,7 +238,7 @@ jobs:
       - name: Install Flatpak tools
         run: |
           sudo apt-get update
-          sudo apt-get install -y dbus-x11 flatpak flatpak-builder
+          sudo apt-get install -y dbus-x11 flatpak flatpak-builder xvfb
           flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
 
       - name: Download Linux deb artifact
@@ -294,6 +294,21 @@ jobs:
             cat /tmp/youwee-ytdlp-version.txt
           '
 
+      - name: Smoke test Flatpak launch
+        run: |
+          set -eu
+          set +e
+          xvfb-run -a dbus-run-session -- \
+            timeout --foreground 10s flatpak run com.vanloctech.youwee \
+            >/tmp/youwee-flatpak-launch.log 2>&1
+          STATUS=$?
+          set -e
+          cat /tmp/youwee-flatpak-launch.log
+          if [ "$STATUS" -ne 124 ]; then
+            echo "Youwee Flatpak exited before the launch smoke-test timeout (status $STATUS)."
+            exit "$STATUS"
+          fi
+
       - name: Upload Flatpak artifact
         uses: actions/upload-artifact@v6
         with:

diff --git a/.github/workflows/flatpak-test.yml b/.github/workflows/flatpak-test.yml
@@ -1,9 +1,15 @@
 name: Linux Flatpak Test Build
 
 on:
+  pull_request:
+    paths:
+      - '.github/workflows/flatpak-test.yml'
+      - 'flatpak/**'
+      - 'scripts/fix-deb-deep-link-desktop-entry.sh'
+      - 'src-tauri/**'
   push:
     branches:
-      - feat/flatpak-build
+      - main
   workflow_dispatch:
 
 permissions:
@@ -51,7 +57,8 @@ jobs:
             patchelf \
             libssl-dev \
             libgtk-3-dev \
-            libayatana-appindicator3-dev
+            libayatana-appindicator3-dev \
+            xvfb
           flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
 
       - name: Install frontend dependencies
@@ -130,6 +137,21 @@ jobs:
             cat /tmp/youwee-ytdlp-version.txt
           '
 
+      - name: Smoke test Flatpak launch
+        run: |
+          set -eu
+          set +e
+          xvfb-run -a dbus-run-session -- \
+            timeout --foreground 10s flatpak run com.vanloctech.youwee \
+            >/tmp/youwee-flatpak-launch.log 2>&1
+          STATUS=$?
+          set -e
+          cat /tmp/youwee-flatpak-launch.log
+          if [ "$STATUS" -ne 124 ]; then
+            echo "Youwee Flatpak exited before the launch smoke-test timeout (status $STATUS)."
+            exit "$STATUS"
+          fi
+
       - name: Upload Linux test artifacts
         uses: actions/upload-artifact@v6
         with:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Browser extension download settings** - Preserve global Youwee download settings such as container, output folder, playlists, and subtitles when a browser extension starts a download
 - **AppImage runtime compatibility** - Rebuild Linux AppImages without bundled Wayland, GLib, and GStreamer runtime libraries that can conflict with newer Mesa and WebKitGTK, preventing blank startup windows on modern Linux distributions
 - **Auto subtitle language selection** - Respect selected languages for automatic subtitles instead of requesting every available or translated subtitle language
+- **Flatpak startup compatibility** - Use the stable GNOME Platform 49 runtime while WebKitGTK 2.52 startup crashes are investigated, avoid initializing the unavailable system tray runtime inside Flatpak, and smoke-test the packaged app under Xvfb in CI
 
 ### Changed
 - **AppImage release validation** - Validate the rebuilt AppImage runtime layout in Linux CI and re-sign the finalized artifact for updater integrity

diff --git a/docs/CHANGELOG.vi.md b/docs/CHANGELOG.vi.md
@@ -11,6 +11,7 @@ và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Cài đặt tải từ browser extension** - Giữ lại các cài đặt Youwee global như container, thư mục đầu ra, playlist và subtitle khi browser extension bắt đầu tải xuống
 - **Tương thích runtime AppImage** - Đóng gói lại AppImage Linux không kèm các thư viện runtime Wayland, GLib và GStreamer có thể xung đột với Mesa và WebKitGTK mới hơn, tránh cửa sổ trắng khi khởi động trên các bản Linux hiện đại
 - **Chọn ngôn ngữ subtitle tự động** - Tôn trọng các ngôn ngữ đã chọn cho subtitle tự động thay vì yêu cầu mọi ngôn ngữ subtitle có sẵn hoặc được dịch
+- **Tương thích khởi động Flatpak** - Dùng GNOME Platform 49 ổn định trong khi điều tra crash khởi động của WebKitGTK 2.52, không khởi tạo system tray không có trong runtime Flatpak, đồng thời smoke-test app đã đóng gói với Xvfb trong CI
 
 ### Thay đổi
 - **Kiểm tra release AppImage** - Kiểm tra layout runtime AppImage sau khi đóng gói lại trong CI Linux và ký lại artifact hoàn chỉnh để đảm bảo tính toàn vẹn khi cập nhật

diff --git a/docs/CHANGELOG.zh-CN.md b/docs/CHANGELOG.zh-CN.md
@@ -11,6 +11,7 @@ Youwee 的所有重要更改都将记录在此文件中。
 - **浏览器扩展下载设置** - 浏览器扩展启动下载时保留 Youwee 的全局设置，例如容器、输出目录、播放列表和字幕
 - **AppImage 运行时兼容性** - 重新打包 Linux AppImage，不再捆绑可能与新版 Mesa 和 WebKitGTK 冲突的 Wayland、GLib 与 GStreamer 运行时库，避免现代 Linux 发行版启动时出现白色窗口
 - **自动字幕语言选择** - 自动字幕现在会遵循已选择的语言，而非请求所有可用或翻译后的字幕语言
+- **Flatpak 启动兼容性** - 在调查 WebKitGTK 2.52 启动崩溃期间使用稳定的 GNOME Platform 49 运行时，不再在 Flatpak 内初始化运行时缺失的系统托盘，并在 CI 中通过 Xvfb 对打包应用进行启动冒烟测试
 
 ### 变更
 - **AppImage 发布验证** - 在 Linux CI 中验证重新打包后的 AppImage 运行时布局，并重新签名最终产物以确保更新完整性

diff --git a/flatpak/com.vanloctech.youwee.yml b/flatpak/com.vanloctech.youwee.yml
@@ -1,6 +1,6 @@
 id: com.vanloctech.youwee
 runtime: org.gnome.Platform
-runtime-version: '50'
+runtime-version: '49'
 sdk: org.gnome.Sdk
 command: youwee
 

diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs
@@ -60,6 +60,13 @@ fn configure_linux_webkit_env() {
     }
 }
 
+/// Flatpak's GNOME runtime does not ship an AppIndicator implementation. Avoid
+/// initializing Tauri's system tray there, as it would abort the application
+/// before the WebView can start.
+fn should_setup_system_tray() -> bool {
+    !cfg!(target_os = "linux") || std::env::var_os("FLATPAK_ID").is_none()
+}
+
 /// Show the main window and restore dock icon if needed
 fn show_main_window(app_handle: &tauri::AppHandle) {
     if let Some(window) = app_handle.get_webview_window("main") {
@@ -288,8 +295,11 @@ pub fn run() {
             // Start background channel polling
             services::polling::start_polling(app.handle().clone());
 
-            // Setup system tray
-            setup_tray(app)?;
+            if should_setup_system_tray() {
+                setup_tray(app)?;
+            } else {
+                log::info!("System tray is disabled inside Flatpak");
+            }
 
             if has_initial_links || !has_cli_request {
                 show_main_window(&app.handle());
@@ -306,16 +316,18 @@ pub fn run() {
         })
         .on_window_event(|window, event| {
             // Close-to-tray: hide window instead of quitting
-            if let tauri::WindowEvent::CloseRequested { api, .. } = event {
-                api.prevent_close();
-                let _ = window.hide();
-
-                // macOS: optionally hide the dock icon too
-                #[cfg(target_os = "macos")]
-                if HIDE_DOCK_ON_CLOSE.load(Ordering::SeqCst) {
-                    let _ = window
-                        .app_handle()
-                        .set_activation_policy(tauri::ActivationPolicy::Accessory);
+            if should_setup_system_tray() {
+                if let tauri::WindowEvent::CloseRequested { api, .. } = event {
+                    api.prevent_close();
+                    let _ = window.hide();
+
+                    // macOS: optionally hide the dock icon too
+                    #[cfg(target_os = "macos")]
+                    if HIDE_DOCK_ON_CLOSE.load(Ordering::SeqCst) {
+                        let _ = window
+                            .app_handle()
+                            .set_activation_policy(tauri::ActivationPolicy::Accessory);
+                    }
                 }
             }
         })
@@ -605,6 +617,10 @@ fn setup_tray(app: &tauri::App) -> Result<(), Box<dyn std::error::Error>> {
 /// Rebuild the system tray menu with current followed channels and new video counts.
 /// Called after follow/unfollow, polling finds new videos, or downloads complete.
 pub fn rebuild_tray_menu(app_handle: &tauri::AppHandle) {
+    if !should_setup_system_tray() {
+        return;
+    }
+
     if let Err(e) = rebuild_tray_menu_inner(app_handle) {
         log::error!("Failed to rebuild tray menu: {}", e);
     }