Если программа работает в X11, но не в Wayland, сначала выясните, какой графический backend она реально использует. В Wayland-сессии приложение может быть нативным клиентом Wayland или X11-клиентом через XWayland. Эти пути используют разные плагины и могут по-разному вести себя при создании окна, аппаратном ускорении, захвате экрана и глобальных горячих клавишах.
Не добавляйте набор случайных flags в desktop-файл. Сделайте два запуска одной сборки в одной пользовательской сессии: штатный native и документированный XWayland fallback. Если fallback открывается, executable и большая часть приложения исправны; граница проблемы находится в Wayland backend, GPU или интерфейсе compositor.
Четыре признака описывают среду точнее слова Linux
| Признак | Пример значения | Что показывает |
|---|---|---|
| XDG_SESSION_TYPE | wayland | тип текущей desktop-сессии |
| WAYLAND_DISPLAY | wayland-0 | сокет Wayland compositor |
| DISPLAY | :0 | доступность X/XWayland |
| toolkit backend | wayland или x11/xcb | каким путём создаётся окно |
| stderr до окна | plugin/GPU/portal error | последняя успешная фаза |
Снимайте переменные из того же launch context, что использует пользователь. Процесс из терминала, systemd user service и launcher способны получить разное окружение. Не пересылайте весь `env`: в нём бывают токены. Достаточно нескольких display-переменных, desktop name, версии дистрибутива, compositor и приложения.
Native Wayland и XWayland — два контрольных режима
Wayland — протокол между клиентом и compositor; это не единый сервер с одинаковой реализацией на всех рабочих столах. XWayland запускает X11-приложение как клиента Wayland compositor и служит совместимым путём. Работа через XWayland полезна как временная диагностика, но не подтверждает корректность native режима.
printf 'session=%s\nwayland=%s\ndisplay=%s\ndesktop=%s\n' \
"$XDG_SESSION_TYPE" "$WAYLAND_DISPLAY" "$DISPLAY" "$XDG_CURRENT_DESKTOP"
# Electron 38+: контролируемый fallback
./my-app --ozone-platform=x11
# Qt: по очереди проверить плагины
QT_QPA_PLATFORM=wayland ./my-app
QT_QPA_PLATFORM=xcb ./my-appДля Electron 38 документация фиксирует `--ozone-platform=auto` по умолчанию в Wayland-сессии и возможность принудительного XWayland через `--ozone-platform=x11`. Старую переменную `ELECTRON_OZONE_PLATFORM_HINT` больше нельзя считать рабочим решением. В Qt backend выбирает QPA; `QT_QPA_PLATFORM` или `-platform` подходит для контролируемого теста.
Окно не появилось и окно чёрное — разные сбои
Отсутствие окна с ошибкой platform plugin обычно возникает раньше GPU-рендеринга. Чёрное или мерцающее окно уже указывает на создание surface и проблемы EGL/Vulkan, драйвера либо обмена buffers. Сверьте stderr, renderer information и поведение software rendering только как диагностический эксперимент; постоянно отключать GPU для всех пользователей без оценки производительности не стоит.
- Проверить наличие backend/plugin, который соответствует собранному toolkit.
- Сравнить свежий поддерживаемый GPU driver и software-rendering test.
- Убрать устаревшие flags из launcher и проверить чистый профиль конфигурации.
- Повторить на втором compositor, если ошибка похожа на несовместимость протокола.
Захват экрана и выбор файлов проходят через portals
Приложение может открыть обычное окно, но «не работать» только при screen capture. Wayland намеренно не даёт клиенту свободно читать поверхность других окон. XDG Desktop Portal создаёт ScreenCast session, показывает пользователю выбор источника и после Start возвращает PipeWire streams. Прямой X11-захват в native Wayland не заменяет этот процесс.
Проверьте, установлен ли backend portal для desktop environment, доступна ли user D-Bus session и появляется ли системный диалог. Отсутствие диалога и отказ пользователя — разные результаты. Автоматически нажимать разрешение или обходить portal нельзя; приложение должно обработать cancel и объяснить, как повторить действие.
Релизная матрица фиксирует поддерживаемый путь
- Запустить чистую сборку в X11 и Wayland-сессиях.
- В Wayland проверить native backend и объявленный XWayland fallback.
- Пройти создание окна, resize, scaling, clipboard, drag-and-drop и dialogs.
- Отдельно проверить screen capture через portal и отказ пользователя.
- Собрать crash/log без секретов и подтвердить корректное завершение процесса.
Исправление готово, когда приложение выбирает поддерживаемый backend предсказуемо, не требует устаревшей переменной, показывает окно на заявленных compositor и корректно сообщает об ограниченной функции. Для воспроизведения приложите package format, toolkit/runtime version, GPU/driver, desktop/compositor и короткий stderr от каждого режима.