---
title: Hyprland のセッション環境とデスクトップ連携診断
url: https://doc.liz6.com/ja/tools/hyprland/07-session-troubleshooting
locale: ja
area: tools
tags:
- Hyprland
- 開発ツール
- Hyprland デスクトップ
date: 2026-09-15
modified: 2026-09-15
description: 起動元、PATH、Wayland の寿命、portal、入力、音声を状態とログから限定的に切り分ける。
---

# Hyprland のセッション環境とデスクトップ連携診断

端末では動くのにショートカットから失敗する場合、環境差が考えられる。サービスが active でも正しい画面へ接続できているとは限らない。起動元、環境、実際の API 動作を分ける。

## 三つの問い

どの部品が失敗したか、誰が起動したか、どのセッションへ接続したかを確認する。操作と時刻を記録してから対象ログを読む。最初に全再起動すると証拠を失うことがある。

## シェルとサービスの環境

zshrc の PATH 追加はユーザーサービスへ自動で反映されない。端末側では次を確認する。

```bash
command -v ghostty
printf '%s\n' "$PATH"
```

systemctl --user show-environment と必要変数だけ比較する。全環境の公開は避ける。

独自セッションでは合成器が環境を作った後、依存サービス起動前に必要変数を取り込む。

```bash
systemctl --user import-environment WAYLAND_DISPLAY DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE HYPRLAND_INSTANCE_SIGNATURE
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE HYPRLAND_INSTANCE_SIGNATURE
```

正しいグラフィカルセッション内で実行する。Wayland 環境のない遠隔シェルからでは補えない。配布版の管理や UWSM を使用する場合、その寿命管理に従う。

## 順序と寿命

After は順序、Wants は起動依存、PartOf は停止・再起動の伝播を表す。実在する session target と管理者が必要である。

次は doc-shell.service の説明用例で、正しく管理される hyprland-session.target、qs、Caelestia を前提とする。

```ini
[Unit]
Description=Example desktop shell
PartOf=hyprland-session.target
After=graphical-session-pre.target
ConditionEnvironment=WAYLAND_DISPLAY

[Service]
ExecStart=/usr/bin/qs -c caelestia -n
Restart=on-failure
RestartSec=2

[Install]
WantedBy=hyprland-session.target
```

既存外殻と同時に有効化しない。ConditionEnvironment は変数の存在しか見ず、socket の生存を保証しない。セッション終了時は所属サービスを停止する必要がある。[systemd のセッション規約](https://www.freedesktop.org/software/systemd/man/latest/systemd.special.html)

## 画面共有とファイル選択

アプリは xdg-desktop-portal と選択されたバックエンドを使う。導入済みだけでは経路が正しいと分からない。サービス名は配布版に合わせる。

```bash
systemctl --user status xdg-desktop-portal.service xdg-desktop-portal-hyprland.service
journalctl --user -u xdg-desktop-portal.service -b -n 80 --no-pager
```

XDG_CURRENT_DESKTOP、選択設定、セッション、PipeWire を確認する。ファイル選択だけ動く場合は screencast を調べる。機能ごとに別バックエンドもあり、他を一律削除しない。[Hyprland portal](https://wiki.hypr.land/Hypr-Ecosystem/xdg-desktop-portal-hyprland/)

## 入力と音声

Wayland、XWayland、GTK、Qt を別に試す。Fcitx5 プロセスの存在だけでなく、アプリ統合と現在の入力グループを確認する。[Neovim 入力](../nvim/06-remote-input.md)

```bash
wpctl status
wpctl get-volume @DEFAULT_AUDIO_SINK@
```

既定デバイスと実ストリームを先に見る。既定の変更と既存ストリームの移動は別で、アプリが経路を保持する場合がある。

## 復旧範囲を限定する

| 症状 | 最初の確認 | 復旧対象 |
| --- | --- | --- |
| 外殻だけ消える | QML とサービスログ | 外殻 |
| キー起動に失敗 | パスと環境 | 命令・サービス環境 |
| ログアウト後も残る | target とプロセス | 停止伝播 |
| 共有画面が空 | portal、PipeWire、環境 | 対応経路 |
| 配色の部分失敗 | 出力と再読み込み | 該当アプリ |

修正後は元の操作と再ログインを試す。実行中の修正が成功しても次回起動順が正しいとは限らない。