本文用「桌面環境」泛指使用者看到的圖形介面整體。技術上，Hyprland 是 Wayland compositor——負責視窗合成和輸入管理，不含完整桌面環境（DE）的套件管理、設定面板等元件。GNOME、KDE Plasma 才是完整的 DE。但在故障隔離的討論中，關鍵區分是 kernel space vs userspace，compositor 和 DE 都在 userspace 這一側。

Kernel 與 Userspace 的隔離邊界

作業系統分成兩個執行空間。Kernel space 負責硬體驅動、記憶體管理、process 排程這些基礎設施。Userspace 跑所有應用程式，包括桌面環境本身。

兩個空間之間有硬體層級的隔離——CPU 的保護環機制（ring 0 是核心層級、ring 3 是應用程式層級，硬體強制限制 ring 3 的程式碼存取 ring 0 的記憶體）。Userspace 的 process 不管怎麼崩潰，都不會直接影響 kernel。Kernel 會清理掉崩潰的 process、回收它佔用的記憶體，然後繼續運作。

這個隔離機制解釋了一個關鍵差異：為什麼 Linux 上一個 app crash 通常只是那個視窗消失，而不會拖垮整台機器。

為什麼 Windows 會藍屏

Windows 的藍屏（Blue Screen of Death, BSOD）是 kernel panic 的表現——作業系統核心本身遇到無法恢復的錯誤，只能停機。

Windows 藍屏頻率較高的結構性原因在於顯示驅動的執行位置。Windows 把 GPU 驅動放在 kernel mode（WDDM 架構），NVIDIA 或 AMD 的驅動程式碼直接跑在核心空間。驅動有 bug 時，錯誤發生在 kernel space，清理掉再繼續的選項不存在——繼續執行可能造成資料損壞，只能停機。

藍屏頻率高是架構選擇的代價。把驅動放在 kernel mode 可以減少 context switch 的效能開銷，GPU 效能更好。代價是驅動 bug 的爆炸半徑從「app crash」升級成「整台停機」。Windows 10/11 已加入 TDR（Timeout Detection and Recovery）機制——GPU driver hang 時系統嘗試 reset driver 而非直接藍屏，大幅降低了 GPU 導致的 BSOD 頻率。但架構上 driver 仍在 kernel mode，藍屏的可能性仍然存在。

Linux 桌面的架構差異

Linux 桌面環境的顯示合成器（Hyprland、Sway、KDE Plasma 的 KWin）跑在 userspace。它們透過 DRM/KMS（Direct Rendering Manager / Kernel Mode Setting，Linux 的顯示子系統介面）跟 kernel 的 GPU 驅動溝通，但合成器本身的程式碼不在 kernel space 裡。

這個架構選擇的效果：

Compositor crash。Hyprland 如果遇到 segfault 或其他 fatal error，kernel 終止這個 userspace process。所有由它管理的視窗消失，螢幕回到 TTY 登入畫面或黑屏。但 kernel 還在跑——其他 TTY 可以登入，SSH 可以連線，背景的 service 繼續運作。

GPU driver bug。Linux 的 GPU 驅動分兩層：kernel module（可動態載入的核心擴充模組，如 nvidia.ko、amdgpu.ko）負責硬體操作，userspace 的 Mesa / NVIDIA userspace driver 負責 OpenGL/Vulkan 實作。Kernel module 出問題理論上可以 kernel panic，但實際行為取決於驅動。AMD 的開源 amdgpu 通常會嘗試 reset GPU 而非直接 panic，常見的表現是畫面凍結幾秒後恢復。NVIDIA 的閉源 nvidia.ko 是隔離模型的主要例外——kernel 社群無法審查或修復其程式碼，hang 時恢復能力遠弱於 amdgpu，經常拖垮整個 session 且 TTY 切換也受影響。這是後續故障場景中 NVIDIA 相關 caveat 的根源。

應用程式 crash。Firefox、VS Code、任何 GUI 程式崩潰，只有那個視窗消失。Compositor 繼續管理剩下的視窗，桌面環境不受影響。

TTY：kernel 存活時的首選救生通道

TTY（TeleTYpewriter）是 Linux 核心直接提供的純文字終端機介面，獨立於任何桌面環境。systemd 預設配置下有 6 個 virtual console（TTY1-TTY6）。Wayland compositor（如 Hyprland）通常佔用 TTY1，其餘可用。

切換方式：Ctrl+Alt+F2（切到 TTY2）到 Ctrl+Alt+F6（切到 TTY6）。

TTY 的重要性在於它不依賴 compositor。Hyprland 掛了、compositor crash 導致桌面消失——只要 kernel 還活著、GPU driver 仍能處理 VT switch，TTY 就能切過去登入操作：

• 用 htop 或 ps 查看哪個 process 出問題
• kill 有問題的 process
• 用 vim 或 nano 修改配置檔
• 重新啟動 Hyprland（Hyprland 指令）
• 如果需要，正常 reboot

TTY 切換失效的情境有兩種：kernel panic（極罕見）和 GPU 完全 hang 導致 VT switch 本身卡住（NVIDIA 閉源驅動在 Wayland 上較常見，需確保 nvidia_drm.modeset=1）。後者的替代手段是 SSH 遠端登入或 Magic SysRq 鍵（見常見故障場景的場景三）。

記憶體耗盡（OOM）的處理機制

Linux kernel 有 OOM Killer（Out of Memory Killer）機制——當記憶體和 swap 都用完、kernel 無法再分配新頁面時，自動挑選佔用記憶體最多、重要性最低的 process 強制終止，釋放記憶體讓系統繼續運作。

OOM Killer 的行為有時超出使用者的預期——它可能直接終止 Hyprland（因為 compositor 通常佔用不少記憶體），導致桌面突然消失。但關鍵是：系統沒有崩潰。Kernel 還在、TTY 還在、SSH 還在。

預防 OOM 的常見做法：

• 設定 swap（即使用 SSD，2-4GB 的 swap 也能在記憶體壓力大時提供緩衝）
• 啟用 systemd-oomd（userspace 的 OOM 管理，比 kernel OOM Killer 更早介入、更可控）
• 監控記憶體用量（btop 或 htop 可以看即時狀態）

故障層級速查

前五個層級都有恢復手段，只有 kernel panic 需要重開機。日常使用中遇到的故障多數落在前三層。

核心套件

1sudo pacman -S hyprland xorg-xwayland xdg-desktop-portal-hyprland

[VM 可測試] 套件安裝本身在 VM 和實機上完全相同。

GPU 驅動

GPU 驅動決定 Hyprland 的渲染是走硬體加速還是軟體 fallback。AMD 和 Intel 開箱即用，NVIDIA 需要額外配置。

AMD（推薦，開箱即用）

1sudo pacman -S mesa vulkan-radeon libva-mesa-driver mesa-vdpau

mkinitcpio MODULES 加入：amdgpu

環境變數（放在 Hyprland 配置裡）：

1env = {
2    "LIBVA_DRIVER_NAME, radeonsi",
3    "VDPAU_DRIVER, radeonsi",
4    "AMD_VULKAN_ICD, RADV",
5}

AMD 是 Hyprland / Wayland 生態支援最好的 GPU。如果是新購硬體、有選擇的餘地，AMD 是最省事的選項。

Intel（開箱即用）

1sudo pacman -S mesa vulkan-intel intel-media-driver

mkinitcpio MODULES 加入：i915

1env = {
2    "LIBVA_DRIVER_NAME, iHD",
3    "VDPAU_DRIVER, va_gl",
4}

Intel 內顯在 Wayland 上表現穩定，適合筆電和輕度桌面使用。

NVIDIA（需要額外配置，非官方支援）

[需實機測試] NVIDIA 的所有設定在 VM 中無意義——VM 使用 virtio-gpu 或軟體渲染，不走 NVIDIA 驅動。以下步驟只在實體機有 NVIDIA 顯卡時才需要。

Hyprland 官方不支援 NVIDIA，但社群有成熟的 workaround。最低版本需求：

• NVIDIA driver >= 555（555 引入完整 GBM 支援和 explicit sync，是 Wayland 硬體渲染的最低依賴。535 系列有 explicit sync 問題，Wayland 下容易 flicker。590+ 修復多數 HDR 和多螢幕邊界問題）
• xorg-xwayland >= 24.1
• wayland-protocols >= 1.34

安裝：

1sudo pacman -S nvidia-dkms nvidia-utils libva-nvidia-driver
2# 32-bit 支援（遊戲可能需要）：
3sudo pacman -S lib32-nvidia-utils

mkinitcpio MODULES（依硬體配置選擇）：

純 NVIDIA 桌機：

1MODULES=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)

Intel + NVIDIA hybrid 筆電（Intel 排在 NVIDIA 前面）：

1MODULES=(i915 nvidia nvidia_modeset nvidia_uvm nvidia_drm)

更新 initramfs：

1sudo mkinitcpio -P

Modprobe 設定：

1# /etc/modprobe.d/nvidia.conf
2options nvidia_drm modeset=1

GRUB kernel parameter：

1# /etc/default/grub
2GRUB_CMDLINE_LINUX_DEFAULT="... nvidia_drm.modeset=1 nvidia_drm.fbdev=1"

更新 GRUB：

1sudo grub-mkconfig -o /boot/grub/grub.cfg

Hyprland 配置裡的 NVIDIA 環境變數：

1env = {
2    "LIBVA_DRIVER_NAME, nvidia",
3    "__GLX_VENDOR_LIBRARY_NAME, nvidia",
4    "GBM_BACKEND, nvidia-drm",         -- 如果 Firefox crash，移除這行
5    "NVD_BACKEND, direct",
6}

Cursor 修正（NVIDIA 常見的硬體 cursor 問題）：

1hl.config({
2    cursor = {
3        no_hardware_cursors = true,
4        allow_dumb_copy = true,
5    },
6})

Suspend/resume 支援：

1sudo systemctl enable nvidia-suspend.service nvidia-hibernate.service nvidia-resume.service

檢查 GPU 驅動狀態

1lspci -k | grep -A 3 VGA        # 查看使用中的驅動
2glxinfo | grep "OpenGL renderer" # 查看活躍的 renderer
3vulkaninfo --summary             # Vulkan 裝置資訊

GPU 驅動相關的故障診斷（driver hang、畫面凍結、suspend/resume 後異常）見桌面環境維護與故障排除。

桌面配套套件

Hyprland 只管視窗，以下是一個可用桌面需要的配套工具：

 1sudo pacman -S \
 2  kitty waybar wofi mako \
 3  polkit-gnome grim slurp wl-clipboard cliphist \
 4  hyprpaper hyprlock hypridle \
 5  pipewire pipewire-alsa pipewire-jack pipewire-pulse wireplumber \
 6  pamixer pavucontrol brightnessctl \
 7  bluez bluez-utils blueman \
 8  networkmanager network-manager-applet \
 9  thunar gvfs \
10  qt5-wayland qt6-wayland \
11  ttf-meslo-nerd noto-fonts noto-fonts-cjk

AUR 補充套件（用 yay 或 paru）：

1yay -S grimblast-git   # Hyprland 截圖 wrapper
2yay -S swww            # 動態桌布（hyprpaper 的替代）
3yay -S rofi-wayland    # 功能比 wofi 更豐富的 launcher

[已驗證] 套件安裝在 VM 中完全可執行。waybar、wofi、mako、hyprlock 在 virtio-gpu-gl-pci 加速下正常 render（Hyprland 0.55 + UTM 4.7.5 實測）。

[需實機測試] 藍牙（bluez）、亮度（brightnessctl）、音訊裝置偵測（pipewire）需要實際硬體。

登入管理器

Hyprland 預設不含登入管理器。三個選項：

從 TTY 直接啟動（最簡單）

登入文字介面後直接執行 Hyprland。建議用 wrapper script 設定必要的環境變數：

1#!/bin/sh
2# ~/start-hyprland.sh
3export XDG_SESSION_TYPE=wayland
4export XDG_CURRENT_DESKTOP=Hyprland
5export XDG_SESSION_DESKTOP=Hyprland
6exec Hyprland

1chmod +x ~/start-hyprland.sh
2~/start-hyprland.sh

greetd + tuigreet（推薦）

greetd 是一個輕量的登入管理器，tuigreet 是它的 TUI 前端：

1sudo pacman -S greetd greetd-tuigreet

設定 /etc/greetd/config.toml：

1[terminal]
2vt = 1
3
4[default_session]
5command = "tuigreet --cmd Hyprland"
6user = "greeter"

自動登入（可選）：

1[initial_session]
2command = "Hyprland"
3user = "yourusername"

啟用服務：

1sudo systemctl enable greetd

SDDM

如果已經有 KDE 或偏好圖形化登入介面：

1sudo pacman -S sddm
2sudo systemctl enable sddm

SDDM 會自動偵測到 Hyprland 並在登入畫面顯示它作為 session 選項。

[VM 可測試] 登入管理器的設定在 VM 中可完整測試。

首次啟動常見問題

配置格式：Lua 取代 hyprlang（v0.55+）

Hyprland v0.55（2026 年 4 月）起，配置格式從 hyprlang（.conf）遷移到 Lua（.lua）。舊的 hyprland.conf 在沒有 .lua 檔案時仍然可用，但 hyprlang 已被標記為 deprecated，預計在後續版本移除。

遷移工具：hyprlang2lua（Go，有瀏覽器版）、hyprconf2lua（Python pip）、hypr-migrate。

本系列後續文章（Hyprland 核心配置、Workspace 與外觀、Caelestia）都使用 Lua 格式。如果在網路上看到 .conf 格式的教學，多數仍然可用，但建議儘早遷移到 Lua。

拆分配置用 Lua 原生的 require()：

1-- hyprland.lua
2require("keybinds")    -- 載入同目錄下的 keybinds.lua
3require("rules")       -- 載入同目錄下的 rules.lua
4require("appearance")

詳細的配置語法和設定邏輯在核心配置和 Workspace、Window Rules 與外觀。

其他發行版

Fedora

Fedora 39 起即在官方 repo。安裝：

1sudo dnf install hyprland

JaKooLit 提供自動化安裝腳本（github.com/JaKooLit/Fedora-Hyprland），Fedora 42+ 運作良好。

NixOS

NixOS 有官方 module，在 configuration.nix 加入：

1programs.hyprland.enable = true;

Home Manager 也有對應 module，可以宣告式管理 Hyprland 配置。

Ubuntu

不推薦。Ubuntu 的 point-release 模型跟 Hyprland 的 bleeding-edge 更新節奏衝突。沒有官方 PPA，從 source 編譯可行但維護成本高。如果一定要用 Debian 系，Arch 的 rolling release 或 Fedora 的半年週期更適合 Hyprland。

安裝後的下一步

安裝完成後，VM 環境的額外設定（環境變數、效能調整、測試矩陣）見 VM 環境設定與測試矩陣。配置檔的組織方式和 keybind 設計見 Hyprland 核心配置。

Caelestia 這類「desktop shell 專案」做的就是把上述元件統一設計、統一配色、統一出貨，省去自己一個個挑的功夫。它用的是 Quickshell（QML 框架）把所有元件包成一套風格一致的桌面。本模組教的是自己組裝的方式——理解各元件的配置，之後要用 Caelestia 或自己拼都能做。

Waybar：狀態列

Waybar 是 Hyprland 桌面最常用的狀態列。配置在 ~/.config/waybar/，分兩個檔案：config.jsonc（結構和模組）和 style.css（外觀）。

結構配置

 1// ~/.config/waybar/config.jsonc
 2{
 3    "layer": "top",
 4    "position": "top",
 5    "height": 36,
 6    "spacing": 4,
 7
 8    // 左中右三區塊各放哪些模組
 9    "modules-left": ["hyprland/workspaces", "hyprland/window"],
10    "modules-center": ["clock"],
11    "modules-right": ["pulseaudio", "network", "cpu", "memory", "battery", "tray"],
12
13    // 各模組設定
14    "hyprland/workspaces": {
15        "format": "{id}",
16        "on-click": "activate"
17    },
18    "clock": {
19        "format": "{:%H:%M}",
20        "format-alt": "{:%Y-%m-%d %H:%M}",
21        "tooltip-format": "<tt>{calendar}</tt>"
22    },
23    "battery": {
24        "format": "{capacity}% {icon}",
25        "format-icons": ["", "", "", "", ""],
26        "states": {
27            "warning": 30,
28            "critical": 15
29        }
30    },
31    "network": {
32        "format-wifi": "{essid} ({signalStrength}%)",
33        "format-ethernet": "{ifname}",
34        "format-disconnected": "Disconnected"
35    },
36    "pulseaudio": {
37        "format": "{volume}%",
38        "on-click": "pavucontrol"
39    }
40}

format 欄位裡的 icon 字元來自 Nerd Font——終端機與編輯器提到的字型安裝是這裡正常顯示的前提。

外觀 CSS

 1/* ~/.config/waybar/style.css */
 2
 3* {
 4    font-family: "MesloLGS Nerd Font", monospace;
 5    font-size: 13px;
 6}
 7
 8window#waybar {
 9    background-color: rgba(30, 30, 46, 0.85);
10    color: #cdd6f4;
11}
12
13#workspaces button {
14    padding: 0 8px;
15    color: #6c7086;
16    border-radius: 6px;
17}
18
19#workspaces button.active {
20    color: #cdd6f4;
21    background: rgba(137, 180, 250, 0.2);
22}
23
24#clock, #battery, #network, #pulseaudio {
25    padding: 0 10px;
26}
27
28#battery.warning {
29    color: #f9e2af;
30}
31
32#battery.critical {
33    color: #f38ba8;
34}

CSS 裡的色碼（#cdd6f4、#89b4fa、#f38ba8）來自配色方案（這個範例用的是 Catppuccin Mocha）。統一使用同一套色碼是 rice 視覺協調的基礎。

Config 裡的字族名必須跟系統實際安裝的字族逐字相符。Nerd Font 的圖示落在專屬碼位範圍，只有對應的那支字帶這些 glyph——指定一個沒裝的字族名，文字排版引擎找不到 glyph 就會顯示豆腐方塊。確認實裝字族名的方式：

1fc-list | grep -i meslo
2# MesloLGSNerdFont-Regular.ttf: "MesloLGS Nerd Font":style=Regular

引號內的字串是 config 該填的字族名。

同一份 Waybar config 能同時服務筆電、桌機與 VM，靠的是模組對缺少硬體的自動退化：battery 在沒有電池的機器直接隱藏該模組、不報錯也不留空位；pulseaudio 在沒有音訊服務時顯示為空；network 顯示當下實際在用的介面。不必為不同機器維護多份 config——把可能用到的模組都列上，用不到的那台自己消失。

Wofi / Rofi：啟動器

啟動器是按快捷鍵彈出的搜尋框，用來啟動應用程式、執行指令、搜尋檔案。

Wofi（Wayland 原生）配置：

1# ~/.config/wofi/config
2show=drun
3width=600
4height=400
5prompt=Search...
6insensitive=true
7allow_markup=true

 1/* ~/.config/wofi/style.css */
 2window {
 3    background-color: #1e1e2e;
 4    border: 2px solid #89b4fa;
 5    border-radius: 12px;
 6}
 7
 8#input {
 9    background-color: #313244;
10    color: #cdd6f4;
11    border-radius: 8px;
12    margin: 10px;
13    padding: 8px 12px;
14}
15
16#entry:selected {
17    background-color: rgba(137, 180, 250, 0.2);
18}

Rofi（需要 wayland fork rofi-lbonn-wayland）功能更豐富——支援多種 mode（drun、window、ssh、自定義 script）、主題系統更完整。如果需要進階功能（例如 emoji picker、密碼管理器整合），Rofi 是更好的選擇。

Mako / Dunst：通知

Mako 是 Wayland 原生的通知 daemon，負責顯示通知——它監聽 D-Bus 的 org.freedesktop.Notifications 介面、把收到的通知畫出來。產生通知的是應用程式，透過 libnotify 送上 D-Bus。所以一套能用的通知鏈需要兩半：daemon（顯示）和 libnotify（產生與遞送）。缺了 libnotify，連命令列自測用的 notify-send 都沒有。套件清單要同時列 mako 和 libnotify。

配置簡潔：

 1# ~/.config/mako/config
 2font=MesloLGS Nerd Font 11
 3background-color=#1e1e2e
 4text-color=#cdd6f4
 5border-color=#89b4fa
 6border-radius=8
 7border-size=2
 8padding=12
 9default-timeout=5000
10max-visible=3
11
12[urgency=critical]
13border-color=#f38ba8
14default-timeout=0

通知的視覺風格（圓角、配色、字型）要跟 waybar 和啟動器一致，這是整體 rice 不散的關鍵。

Nerd Font 的字符集只含 Latin、圖示與 Powerline 符號，不含中日韓。任何 CJK 文字（通知內文、視窗標題）若系統沒有 CJK 字型可 fallback 會變豆腐方塊。修法是安裝 CJK fallback（如 noto-fonts-cjk），fontconfig 會自動補字、不需改各工具的 config。另外，中途補裝字型後已在跑的 daemon 需重啟才看得到——reload 類指令只重讀設定檔、不重建記憶體中的字型快照（原理見 字型的可用集合在 process 啟動時決定）。

Grim + Slurp：截圖

Grim 負責截圖、Slurp 負責框選區域，兩者搭配使用。截圖結果透過 wl-copy 送進剪貼簿時，需要明確指定 MIME 型別：

1# 全螢幕截圖到剪貼簿
2grim - | wl-copy --type image/png
3
4# 框選區域截圖到剪貼簿
5grim -g "$(slurp)" - | wl-copy --type image/png
6
7# 全螢幕截圖存檔
8grim ~/screenshot.png

wl-copy 不帶 --type 時會嘗試透過 xdg-utils（xdg-mime）推斷 stdin 的型別。最小安裝環境沒有 xdg-utils 的情況下，PNG bytes 會被誤標成 text/plain，貼進影像應用程式就拿不到圖。明確帶 --type image/png 讓行為不依賴環境是否安裝了 xdg-utils。確認剪貼簿內容型別：

1wl-paste --list-types
2# 應顯示 image/png

Hyprland keybind 範例：

1bind = , Print, exec, grim - | wl-copy --type image/png
2bind = SHIFT, Print, exec, grim -g "$(slurp)" - | wl-copy --type image/png

這篇用「圖形檔案管理員」當具體案例，但判讀方式適用於任何你想加進最小環境的桌面 app：先看它的相依樹拖進什麼，再決定值不值得。

三種實作的實測相依

同樣是「有側欄、有選單、能瀏覽掛載裝置」的圖形檔案管理員，三個主流實作在一台已有 GTK3 的 Arch ARM 機器上，各自會新裝的套件數量如下（pacman -S --needed --print 實測）：

差異的來源不是「檔案管理員本身多大」，Thunar 跟 Nemo 的主程式都在 7–10 MB 量級。差的是後面那條相依鏈。

Thunar 與 PCManFM-Qt：桌面無關的獨立程式

Thunar 與 PCManFM-Qt 都是刻意做成「不依賴完整桌面環境」的檔案管理員。Thunar 雖然出身 XFCE，但它拖進的 8 個套件是 XFCE 的基礎函式庫（設定系統 xfconf、工具庫 libxfce4util、UI 庫 libxfce4ui），不是 XFCE 桌面本身——你不會因此裝到 XFCE 的面板、視窗管理器或 session。PCManFM-Qt 走 Qt 棧，帶的 layer-shell-qt 反而是 Wayland 原生整合的加分項。這兩個裝下去，機器還是那台只有 Hyprland 的機器，只是多了一個能開的檔案管理員。

Nemo：為 Cinnamon 而生，假設 Cinnamon 在旁邊

Nemo 是 Cinnamon 桌面的檔案管理員，它的相依反映了這個出身：cinnamon-desktop 提供背景與顯示設定的整合、xapp 是 Cinnamon 系列跨桌面的整合層。即使你只想要「開一個視窗看檔案」，這些桌面元件也會一起裝上，因為 Nemo 在程式碼層面就假設它們存在。這不是 Nemo 寫得差，是它本來就不是設計給「裸 window manager」用的——它預期自己跑在 Cinnamon session 裡。

Nemo 那 36 個套件裡，還有一大塊來自它把 gvfs 列成硬相依（下一節說明 gvfs 是什麼），而 gvfs 又拖進整套磁碟管理棧（udisks2、libblockdev 的 8 個子模組、mdadm、parted、volume_key）。所以 Nemo 的相依樹是「Cinnamon 桌面元件」加「完整磁碟/檔案系統管理」兩層疊起來的結果。

gvfs：側欄那些功能不是檔案管理員自己做的

截圖裡檔案管理員側欄常見的「Devices（掛載裝置）」「Network（瀏覽網路芳鄰）」「Trash（垃圾桶）」，多半不是檔案管理員自己實作的，是 gvfs（GNOME Virtual File System） 這個後端提供的。gvfs 用一層虛擬檔案系統把「掛載 USB 隨身碟」「連 SMB 網路分享」「把檔案丟垃圾桶」這些操作抽象成統一介面，讓檔案管理員不必自己處理每一種裝置與協定。

這帶出一個重要判讀：輕量不是免費的，當功能對等時，相依會靠攏。 Thunar 與 PCManFM-Qt 把 gvfs 列成 optional dependency——不裝也能開檔案管理員，但側欄就沒有掛載、垃圾桶、網路那些功能。要讓輕量檔案管理員有截圖裡那種完整側欄，你得自己補 gvfs，而補上 gvfs 就會連帶拖進它的相依（udisks2、polkit、fuse3、libsecret 等）。Nemo 把 gvfs 設成硬相依，只是把這個選擇替你做了。

所以公平的比較不是「Thunar 8 個 vs Nemo 36 個」，而是「Thunar + gvfs + 縮圖 vs Nemo」。補齊功能後，Thunar 這條路線仍然省下的是 Nemo 獨有的那層——cinnamon-desktop、xapp、xapp-symbolic-icons 這些桌面環境耦合元件。那層，才是「為了一個檔案管理員裝半個 Cinnamon」真正可以省掉的部分。

tumbler：縮圖也是一個額外套件

檔案管理員顯示圖片/影片縮圖，同樣不是內建的，靠的是縮圖服務。Thunar 家族用 tumbler，影片縮圖再另外需要 ffmpegthumbnailer。這是「一個功能對應一個額外套件」的又一個例子——最小環境裡，縮圖、掛載、網路瀏覽每一項都是你明確選擇要不要付相依成本的功能，而不是預設就有。

Wayland / Hyprland 下的注意事項

這些檔案管理員多數是 X11 時代的 GTK/Qt 程式，在 Wayland 下會透過 XWayland 或原生 Wayland 後端執行。PCManFM-Qt 帶的 layer-shell-qt 是 Wayland 的 layer-shell 整合；GTK 的 Thunar/Nemo 在 Wayland 下一般走 GTK 自己的 Wayland 後端。開啟/儲存檔案對話框、拖放、縮圖預覽在裸 Hyprland（沒有完整 portal 服務）下的實際行為，取決於有沒有裝 xdg-desktop-portal 與對應的後端。

[待實機驗證] 以下行為尚未在本系列的 Hyprland 實機環境確認，先標記待驗證：(1) Thunar 補上 gvfs 後，側欄的 Devices/Network/Trash 是否如預期出現並可用；(2) tumbler + ffmpegthumbnailer 的縮圖在 Wayland 下是否正常產生；(3) 三者在裸 Hyprland（無完整桌面 portal）下的檔案對話框與拖放行為；(4) Nemo 在沒有 Cinnamon session 的情況下，桌面圖示、設定整合等功能是否失效或報錯。這些是「相依裝了之後實際好不好用」的問題，相依數量本身（上表）已是實測確定值。

風險與注意事項

移除後的孤兒套件：裝了 Nemo 再反悔移除時，cinnamon-desktop、xapp 那一票被拖進來的相依會變成沒人依賴的孤兒（pacman -Qtd 可列出）。用 pacman -Rns nemo 移除時帶走遞迴相依，或定期清孤兒，否則那半個 Cinnamon 會留在系統裡。輕量檔案管理員因為拖進的東西少，這個問題也小。

桌面環境服務未跑的副作用：把為某個桌面環境寫的 app 裝進裸 window manager，它預期的那些服務不在時，部分功能可能靜默失效或在啟動時報錯。這類問題不會在相依解析階段出現——套件裝得起來，是執行時才發現某個整合功能沒作用。（Nemo 在無 Cinnamon 下的具體表現，見上方待驗證項。）

選型判準：最小化的 Hyprland 想要一個圖形檔案管理員，優先考慮桌面無關的 Thunar 或 PCManFM-Qt；需要截圖那種完整側欄功能時，明確補上 gvfs（掛載/垃圾桶/網路）與 tumbler（縮圖），把相依成本花在你真的要用的功能上。以 Thunar 為例，完整一套是 pacman -S thunar gvfs tumbler ffmpegthumbnailer（gvfs 給掛載/垃圾桶/網路、tumbler + ffmpegthumbnailer 給圖片與影片縮圖）。除非你本來就跑 Cinnamon，否則不建議為了單一檔案管理員把 Nemo 的整套桌面元件裝進來——那是付了桌面環境耦合的代價，卻沒用到那個桌面環境。

待實機驗證清單

這篇的相依數量與相依樹是實測確定的；以下「裝了之後實際體驗」的部分待在 Hyprland 實機補驗證：

• Thunar + gvfs + tumbler + ffmpegthumbnailer 的完整側欄與縮圖行為
• 三種檔案管理員在裸 Hyprland（XWayland vs 原生 Wayland、portal 有無）下的差異
• Nemo 脫離 Cinnamon session 的功能缺損範圍
• 加進 packages-arch.txt 後，bootstrap 一鍵安裝這條路線的實際落地結果

為什麼拿 Nemo 當「重」的代表

上表用 Nemo 當桌面環境耦合的代表，是因為它把耦合展示得最乾淨——cinnamon-desktop + xapp 那層桌面元件加上 gvfs 硬相依，剛好對照出 Thunar / PCManFM-Qt 省掉的是什麼。但它不是最重的：GNOME 的 Nautilus（nautilus）與 KDE 的 Dolphin（dolphin）是更 canonical 的「裝檔案管理員就拖進半個桌面」例子。Nautilus 深度綁 GNOME 的 GTK4 / libadwaita / tracker 索引棧，在非 GNOME 環境裝它會拉進一串 GNOME 平台庫；Dolphin 綁 KDE 的 Frameworks（KIO、Baloo 等），在非 KDE 環境同理。判讀方式跟 Nemo 一節相同：檔案管理員的相依樹反映它預期跑在哪個桌面裡。真要在裸 Hyprland 上驗，pacman -S --needed --print nautilus / dolphin 會列出各自那串平台庫——數量通常比 Nemo 更可觀（實測 Nautilus 72、Dolphin 91，約 Nemo 的 2 到 2.5 倍）。

零相依對照：純終端機檔案管理員

如果你在意的正是相依足跡，還有一條完全繞開圖形棧的路：終端機檔案管理員（yazi / lf / nnn / ranger）在終端機裡跑，不需要 GTK / Qt / gvfs / 桌面環境那一整套。yazi（Rust、內建預覽與非同步 I/O）與 lf、nnn（C、極小）在裸 Hyprland 或純 SSH 環境下都是近乎零額外相依的選擇——你已經有終端機，它們就能跑。代價是純鍵盤操作、沒有圖形檔案管理員那種拖放與縮圖牆。這是「圖形 vs 終端機」的取捨，不是同一條路上的輕重之分：要滑鼠拖放、縮圖預覽走圖形檔案管理員；要零相依、鍵盤流、SSH 下也能用走 TUI。TUI 檔案管理員的比較見 CLI 環境工具的檔案管理器 TUI。

下一步

• 這篇談的是「加桌面 app 時怎麼判讀相依成本」，套件清單本身怎麼設計、怎麼被 bootstrap 一鍵安裝，見 模組八：Bootstrap script 與套件清單。
• Hyprland 本體與配套工具的安裝，見 模組五：安裝與環境建置。
• 這台 Hyprland 是在 VM 上建起來測的，VM 能測什麼、什麼要留到實機，見 VM 環境設定與測試矩陣。

場景一：Hyprland compositor crash

症狀：所有視窗同時消失，螢幕變黑或回到 TTY 登入畫面。滑鼠鍵盤有反應（可以切 TTY），但沒有桌面。

原因：Compositor process 遇到 fatal error 被 kernel 終止。常見觸發條件包括 plugin 相容性問題、特定 Wayland 協議操作觸發的 bug、GPU driver 回傳異常狀態。

恢復步驟：

注意：以下步驟中 killall Hyprland 或重啟 Hyprland 會終止所有由 compositor 管理的視窗，未存檔的工作會遺失。如果可能，先透過 TTY 或 SSH 嘗試存檔（如 kill -USR1 <pid> 對支援的應用程式觸發存檔）。

1. Ctrl+Alt+F2 切到 TTY2
2. 用你的帳號登入
3. 檢查 Hyprland 的最後錯誤訊息：

1# 通用方式（不管 Hyprland 怎麼啟動都有效）
2journalctl -b | grep -i hypr | tail -30
3
4# 如果 Hyprland 是 systemd user unit，可以更精準地查：
5journalctl --user -u hyprland -n 50 --no-pager

4. 重新啟動 Hyprland：

1Hyprland

5. 如果反覆 crash，檢查最近改過的 config：

1cd ~/.config/hypr
2git diff  # 如果 dotfile 有版控

預防：config 改動後用 hyprctl reload 測試，不要直接重啟。啟用 plugin 前確認版本跟 Hyprland 版本相容。

場景二：單一桌面工具掛了

症狀：狀態列（waybar）消失、啟動器（wofi/rofi）叫不出來、通知（mako/dunst）不跳了。桌面其他功能正常，視窗可以操作。

原因：這些工具各自是獨立的 process。掛了只影響自己的功能，不影響 compositor 或其他工具。常見原因是 config 語法錯誤（改完 config 後觸發）、記憶體洩漏（長時間運作後）、或外部服務連線異常（如 waybar 的某個 module 連不到系統匯流排）。

恢復步驟：

判斷啟動方式：如果工具是在 Hyprland config 裡用 exec-once（Hyprland 的自動啟動指令，compositor 啟動時執行一次）啟動的，用 killall + 手動重啟；如果是 systemd user unit，用 systemctl --user。

exec-once 啟動方式（多數 Hyprland 安裝的預設做法）：

1# waybar 掛了
2killall waybar; waybar &
3
4# wofi 掛了
5killall wofi
6# wofi 只在需要時啟動，不用常駐
7
8# mako 掛了
9killall mako; mako &

systemd user unit 啟動方式：

1systemctl --user restart waybar
2systemctl --user restart mako

確認工具是否在跑：

1pgrep waybar  # 有輸出 = 在跑
2pgrep mako    # 沒輸出 = 沒在跑

預防：改 config 後重啟對應的工具確認語法正確。Waybar 的 config 是 JSON 格式，語法錯誤會導致它無法啟動——改完後先用 waybar 前台跑一次看有沒有錯誤訊息。

場景二點五：鎖屏卡死（hyprlock 異常結束）

症狀：鎖屏畫面消失但桌面沒回來，螢幕顯示 Hyprland 的失效保護訊息（「it looks like you locked your screen but the lockscreen app died」），或畫面全黑但系統有回應（SSH 能連、TTY 可能切得到也可能切不到）。

原因：鎖屏工具（Hyprlock、Swaylock）透過 Wayland 的 ext-session-lock 協議向 compositor 請求鎖定。鎖定狀態由 compositor 持有，唯一正常解鎖動作是鎖屏 client 通過認證後呼叫 unlock_and_destroy。如果鎖屏 client 在持鎖狀態下被殺（pkill、crash），compositor 沒收到認證信號，會維持鎖定並顯示失效保護畫面。這跟殺 waybar/mako 不同——那些是普通 process，殺了重啟就好；鎖屏 client 持有安全狀態，殺了反而卡住。

恢復步驟：

1. 嘗試切到另一個 TTY（Ctrl+Alt+F2）。注意：ext-session-lock 的安全語意允許 compositor 攔截 VT 切換快捷鍵，此時 TTY 切不過去，改用 SSH 從另一台機器連入
2. 允許新的鎖屏 client 接管既有的鎖：

1hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1'

3. 重新拉一個鎖屏 client：

1hyprctl --instance 0 'dispatch exec hyprlock'

4. 回到鎖屏畫面，用密碼正常解鎖

判讀：loginctl show-session <id> -p LockedHint 可能顯示 LockedHint=no（logind 層認為沒鎖），但畫面仍進不去——因為擋住畫面的是 compositor 的 ext-session-lock，跟 logind 的提示是獨立的兩層。判斷畫面鎖定狀態看 compositor 層，不看 logind。

預防：測試鎖屏時備好恢復路徑（知道密碼、或預先開 SSH）。不要用殺 process 的方式結束鎖屏——要結束就走認證解鎖。自動化流程若會啟動鎖屏，把「需要人工解鎖」算進代價。鎖屏安全模型的完整說明見 Session Lock。

場景二點六：桌面 shell 畫得出來但互動死掉（進程活著卻 wedged）

症狀：bar / 狀態列還在螢幕上、看起來一切正常，但點它的按鈕（工作區切換、系統匣圖示）沒反應，keybind 叫不出啟動器（wofi / 內建 launcher）。同時焦點視窗（例如終端機）打字完全正常——鍵盤到得了應用程式，只是桌面 shell 的互動死了。

原因：這是跟場景二（工具掛了）不同的一類故障，關鍵差別在進程還活著。場景二是 process 崩潰退出（pgrep 沒輸出），殺了重啟就好；這裡的桌面 shell（如 caelestia / Quickshell）進程還在跑（pgrep 找得到、STAT 是正常的 S、在 poll 等事件、CPU 不高），但它內部的某個子系統初始化失敗了——常見是 QML scene 的某個物件因為上游錯誤沒建起來、變成 null，於是負責「keybind → 開抽屜」「bar 按鈕互動」的模組對 null 讀屬性、整條互動接線死掉。bar 之所以還畫得出來，是它還停在初始化失敗前那一幀的畫面：畫得出來不等於還活著，跟鎖屏那課（畫面有密碼框不等於真的在鎖）是同一個陷阱。

上游觸發常是渲染層。實測案例：VM 的 GPU 只提供到 GLSL 1.20，而 shell 的 shader 需要 GLES 100/300/330，pipeline 建不起來（log 狂噴 Failed to build graphics pipeline state），這次渲染失敗把 scene 初始化打斷，drawers 狀態物件變 null。

診斷（別看 pgrep，讀 shell 自己的 log）：

pgrep 在這裡會騙你——它回報「在跑」，但那不等於「在運作」。權威來源是 shell 自己的 log，而且這種 log 常常不在 journalctl、也不在你猜的路徑，要用該 shell 專屬的 log 指令：

1# caelestia 的例子：用它自己的 CLI 印 shell log
2caelestia shell -l 2>&1 | tail -40
3# 看的是 QML 的 TypeError：對 null 讀屬性 = 那個子系統死了
4#   scene: @modules/Shortcuts.qml: TypeError: Cannot read property 'launcher' of null

另一個活性探針是 shell 的 IPC 回不回真實狀態：正常時查抽屜列表會回傳名字，子系統死掉時回空——這比「進程在不在」精準得多：

1# 子系統活著 → 列出 bar/launcher/session…；死掉 → 回空
2caelestia shell ipc call drawers list

恢復步驟：重啟 shell 讓 scene 重建。以 caelestia 為例：

1caelestia shell -k     # 殺掉卡住的 shell
2caelestia shell -d     # 重新啟動（detached）

驗證修好了，看子系統回來、不是看 pgrep：重啟後 process 一定在（pgrep 本來就會有），要確認的是接線恢復——caelestia shell ipc call drawers list 從「回空」變成列出真實抽屜名、log 不再噴 null 的 TypeError。這對應「重啟成功要驗子系統狀態、不是驗 process 存在」的通用紀律。

判讀與其他場景的界線：pgrep 有輸出 + bar 畫得出來 → 別急著判「正常」；點不動 / keybind 死掉就是 wedged 的訊號，往 shell 自己的 log 查。這跟場景二（process 真的沒了、pgrep 空）、場景三（compositor 整個凍結、連終端機打字都不行）都不同——這裡 compositor 正常、焦點視窗鍵盤正常，只有 shell 的互動接線死。判「進程活著到底有沒有在運作」的通用招式，見 程序、服務與狀態怎麼判。

預防：留意 shell log 裡持續出現的 shader / 渲染 pipeline 錯誤——在 VM 或 GL 支援不足的環境，這類錯誤可能非致命地存在（shell 大致能用），但一次渲染失敗就可能打斷 scene 初始化、把互動接線弄死。VM 環境要確認 GPU 提供的 GL / GLSL 版本足夠（virtio-gpu 走 mesa/zink 提供 GL 3.3+），或在 shell 設定關掉需要高階 shader 的效果。

場景三：GPU driver hang（畫面凍結）

症狀：桌面畫面完全凍結——滑鼠不動、鍵盤不回應、Ctrl+Alt+F2 切 TTY 也沒反應或延遲很久才回應。但如果從另一台機器 SSH 進來，系統是活的，process 都在跑。

原因：GPU driver 進入異常狀態。NVIDIA 閉源驅動在 Linux 上的穩定性不如 AMD 開源驅動（amdgpu），特別是在 Wayland 環境下。常見觸發條件包括 suspend/resume 之後 GPU 沒正確恢復、某些 OpenGL/Vulkan 操作觸發 driver bug、顯示輸出切換（接上或拔掉外接螢幕）。

恢復步驟：

方法 A — 如果 TTY 能切過去：

1# 切到 TTY2
2Ctrl+Alt+F2
3
4# 殺掉 Hyprland（它會帶走所有視窗）
5killall Hyprland
6
7# 重新啟動
8Hyprland

方法 B — 如果 TTY 也凍結、但 SSH 能連：

 1# 從另一台機器 SSH 進來（需事先知道 IP，見下方預防段）
 2ssh user@machine-ip
 3
 4# 殺掉 compositor
 5killall Hyprland
 6
 7# 如果需要 reset GPU（NVIDIA，且 driver 仍回應）
 8# 前提：所有使用 GPU 的 process 已停止（compositor 已 kill）
 9sudo nvidia-smi --gpu-reset
10
11# 切回機器前面重啟 Hyprland

方法 C — 如果完全無回應，先嘗試 Magic SysRq：

Magic SysRq 是 kernel 層級的緊急操作介面，即使 userspace 完全卡死也能回應。按住 Alt+SysRq（筆電通常是 Alt+Fn+SysRq），然後依序按 R E I S U B（每個鍵間隔幾秒）：

• R — 把鍵盤從 raw mode 搶回來
• E — 對所有 process 送 SIGTERM
• I — 對所有 process 送 SIGKILL
• S — sync 所有檔案系統
• U — remount 所有檔案系統為 read-only
• B — 立即 reboot

這比直接斷電安全——sync + unmount 步驟會盡量保護磁碟上的資料。Arch Linux 預設可能停用 SysRq，需在 /etc/sysctl.d/ 設定 kernel.sysrq=1 啟用。

方法 D — 如果 SysRq 也無效，按住電源鍵強制關機：

這是最後手段。Linux 的 ext4/btrfs 檔案系統有 journal 保護，強制關機通常不會損壞檔案系統結構。但 journal 保護的是 metadata 一致性，正在寫入的使用者資料（未存檔的文件、正在下載的檔案）仍然可能遺失或損壞。重開機後正常登入 TTY、啟動 Hyprland 即可。如果開機過程有異常，用 journalctl -b -1 -p err 查看上次開機的錯誤訊息，確認是否有檔案系統修復紀錄。

預防：

• NVIDIA 用戶：關注 driver 版本的 release notes，已知有 Wayland 問題的版本避開
• 配置 suspend 後的 GPU 恢復：在 Hyprland config 或 systemd sleep hook 裡加入 GPU reset 操作
• 事先記錄機器的 IP 位址（ip addr show）或設定固定 hostname（如 mDNS 的 machine.local），桌面凍結時才有辦法從另一台機器 SSH 進來
• 考慮開啟 SSH server，出問題時可以遠端救援。開啟後應配置 key-based authentication 並停用密碼登入（PasswordAuthentication no），避免在網路上暴露密碼登入通道：

1sudo systemctl enable sshd
2sudo systemctl start sshd
3
4# 安全配置：停用密碼登入（確保已設好 SSH key 再改）
5# 編輯 /etc/ssh/sshd_config，設定 PasswordAuthentication no
6# 然後 sudo systemctl restart sshd

場景四：記憶體耗盡（OOM）

症狀：系統變得極慢，操作有明顯延遲（幾秒到幾十秒）。隨後可能某些 process 突然被殺掉——瀏覽器分頁消失、IDE 視窗關閉，嚴重時 Hyprland 本身被 OOM Killer 終止導致桌面消失。

原因：實體記憶體和 swap 都用完了。常見觸發者是瀏覽器（Chrome/Firefox 的分頁越開越多）、IDE（大型專案的 language server）、Docker container、或應用程式的記憶體洩漏。

恢復步驟：

如果還能操作：

1# 找出誰在吃記憶體
2top -o %MEM
3# 或用 htop/btop 的互動介面
4
5# 殺掉佔最多記憶體的 process
6kill <PID>

如果桌面已經被殺、在 TTY 裡：

1# 看 OOM Killer 殺了誰
2journalctl -b | grep -i "out of memory"
3journalctl -b | grep -i "oom"
4
5# 清理完後重啟桌面
6Hyprland

預防：

設定 swap（即使 RAM 夠大，swap 提供 OOM 前的緩衝時間讓你有機會手動清理 process）。RAM 16GB 以上的機器，2-4GB swap 作緩衝通常足夠：

 1# 查看是否有 swap
 2swapon --show
 3
 4# 如果沒有，建立一個 4GB 的 swap file（ext4 檔案系統）
 5sudo fallocate -l 4G /swapfile
 6sudo chmod 600 /swapfile
 7sudo mkswap /swapfile
 8sudo swapon /swapfile
 9
10# 永久生效：加入 /etc/fstab
11echo '/swapfile none swap defaults 0 0' | sudo tee -a /etc/fstab

Btrfs 檔案系統不支援 fallocate 建立 swap file。Btrfs 用戶需改用 btrfs filesystem mkswapfile 或建立專屬的 swap subvolume，具體做法參考 Arch Wiki 的 Btrfs swap 段落。

啟用 systemd-oomd（比 kernel OOM Killer 更早介入、更可控）。systemd-oomd 在 cgroup 的記憶體壓力達到閾值時就開始清理，預設配置對多數桌面場景足夠。進階調整可透過 /etc/systemd/oomd.conf 設定：

1sudo systemctl enable systemd-oomd
2sudo systemctl start systemd-oomd

場景五：Config 寫錯導致 Hyprland 啟動失敗

症狀：從 display manager（圖形登入畫面，如 SDDM、GDM）登入後立刻黑屏又回到登入畫面，或直接回到 TTY。如果從 TTY 手動執行 Hyprland，看到錯誤訊息後立即退出。

原因：Hyprland config 有語法錯誤或引用了不存在的資源。常見錯誤包括 source 指定的檔案不存在、keybind 語法寫錯、monitor 設定格式錯誤。

恢復步驟：

1. 切到 TTY（Ctrl+Alt+F2）
2. 登入後直接跑 Hyprland 看錯誤訊息：

1# 看 Hyprland 的啟動錯誤（也可用 journalctl -b | grep -i hypr）
2Hyprland
3# Hyprland 如果因 config 錯誤無法啟動，會直接印出錯誤訊息後退出

3. 根據錯誤訊息修改 config：

1# Hyprland 的主 config
2vim ~/.config/hypr/hyprland.conf
3
4# 如果用了 source 拆分，錯誤訊息會指出是哪個檔案
5vim ~/.config/hypr/keybinds.conf

4. 修完後重新啟動：

1Hyprland

常見 config 錯誤：

source 路徑錯誤——檔案不存在或路徑拼錯：

1# 確認 source 指定的檔案都存在
2grep "^source" ~/.config/hypr/hyprland.conf
3# 逐一檢查每個路徑

Monitor 設定錯誤——指定了不存在的螢幕名稱：

1# 查看系統實際的螢幕名稱
2# 在能進桌面時記下來，或用 wlr-randr
3wlr-randr

Keybind 語法錯誤——dispatcher 名稱拼錯或參數格式不對。Hyprland 的 keybind 格式是 bind = MOD, key, dispatcher, params，少一個欄位或 dispatcher 拼錯就會報錯。

預防：config 改動時用 hyprctl reload 即時測試，不要改完 config 就直接重啟 Hyprland。如果 dotfile 用 Git 管理，改壞了可以 git checkout 回退。

場景六：Suspend/resume 後桌面異常

症狀：筆電蓋上或手動 suspend 後喚醒，出現以下任一情況——螢幕黑屏但系統有反應（鍵盤背光亮）、解析度跑掉、多螢幕配置丟失（所有視窗擠到一個螢幕）、compositor 直接 crash 回到 TTY。

原因：GPU driver 在 suspend/resume 過程中需要保存和恢復 GPU 狀態。NVIDIA 閉源驅動在 Wayland 上的 suspend/resume 支援不如 AMD 開源驅動穩定，特別是多螢幕配置和高刷新率模式下容易出問題。

恢復步驟：

如果螢幕黑屏但系統有反應：

1# 切到 TTY
2Ctrl+Alt+F2
3
4# 檢查 Hyprland 是否還在跑
5pgrep Hyprland
6
7# 如果在跑但沒畫面，kill 再重啟
8killall Hyprland
9Hyprland

如果解析度或螢幕配置跑掉：

1# 在 Hyprland 內重新套用 monitor 設定
2hyprctl reload

如果 compositor 已經 crash：按場景一的步驟從 TTY 重啟。

預防：

• NVIDIA 用戶：在 /etc/modprobe.d/nvidia.conf 啟用 preserve video memory allocations：

1# /etc/modprobe.d/nvidia.conf
2options nvidia NVreg_PreserveVideoMemoryAllocations=1

同時啟用 NVIDIA 的 suspend/resume systemd service：

1sudo systemctl enable nvidia-suspend
2sudo systemctl enable nvidia-resume
3sudo systemctl enable nvidia-hibernate

• AMD 用戶：amdgpu driver 的 suspend/resume 通常開箱即用，遇到問題先更新 kernel（pacman -Syu linux）。

配置檔位置與格式

Hyprland v0.55 起，配置格式從 hyprlang（.conf）遷移到 Lua（.lua）。主配置檔是 ~/.config/hypr/hyprland.lua。如果 .lua 不存在但 .conf 存在，Hyprland 會回退讀取舊格式，但 hyprlang 已標記為棄用，後續版本會移除支援。

修改後即時生效（不需要重新登入或重啟）。第一次啟動時如果沒有配置檔，Hyprland 會自動產生範例配置。即使配置有語法錯誤，緊急快捷鍵（SUPER+Q 開 terminal、SUPER+M 離開）仍然可用。

[VM 可測試] 配置檔格式和載入行為在 VM 裡跟實機完全相同。

模組化拆分

用 Lua 原生的 require() 拆分配置：

1-- ~/.config/hypr/hyprland.lua — 主入口
2
3require("monitors")      -- 載入 monitors.lua
4require("keybinds")      -- 載入 keybinds.lua
5require("rules")         -- 載入 rules.lua
6require("autostart")     -- 載入 autostart.lua
7require("appearance")    -- 載入 appearance.lua
8require("env")           -- 載入 env.lua

require("monitors") 會從同目錄載入 monitors.lua。拆分的理由是職責分離——改 keybind 不用在千行配置裡找位置，每個子檔案可以獨立 diff 和 rollback。

從舊格式遷移

Hyprland 官方提供遷移工具：hyprlang2lua（Go，也有瀏覽器版）和 hypr-migrate。如果你是從零開始，直接用 Lua 格式。

Monitor 設定

Monitor 設定是硬體相關的核心配置，每台機器都不同。

 1-- ~/.config/hypr/monitors.lua
 2
 3hl.config({
 4    monitor = {
 5        -- 語法："name, resolution@refreshrate, position, scale"
 6        "DP-1, 2560x1440@144, 0x0, 1",
 7        "HDMI-A-1, 1920x1080@60, 2560x0, 1",
 8
 9        -- 筆電內建螢幕
10        "eDP-1, preferred, auto, 1.5",
11
12        -- 預設規則（未明確列出的螢幕）
13        ", preferred, auto, 1",
14
15        -- 鏡像模式（DP-2 鏡像 DP-1 的畫面）
16        -- "DP-2, preferred, auto, 1, mirror, DP-1",
17    },
18})

position 決定多螢幕的空間排列——0x0 是左上角原點，2560x0 表示在第一個螢幕的右邊。scale 處理 HiDPI 顯示（1.5 表示 150% 縮放）。

查詢可用的 monitor 名稱：hyprctl monitors

其他選項：

• transform, 1 — 旋轉（0=正常、1=90 度、2=180 度、3=270 度）
• vrr, 1 — 可變更新率（1=開啟、2=僅全螢幕）
• bitdepth, 10 — 10-bit 色彩

筆電合蓋行為

1-- 合蓋時關閉內建螢幕、開蓋時恢復
2-- bindl = 即使輸入鎖定也能觸發（合蓋時需要）
3hl.bindl("", "switch:on:Lid Switch", "exec", "hyprctl keyword monitor 'eDP-1, disable'")
4hl.bindl("", "switch:off:Lid Switch", "exec", "hyprctl keyword monitor 'eDP-1, preferred, auto, 1'")

[需實機測試] Monitor 位置排列、HiDPI 縮放、VRR、旋轉、多螢幕熱插拔、合蓋行為。VM 通常只有一個虛擬螢幕。

Dotfile 管理策略

Monitor 設定是典型的「機器專屬」配置。如果用 chezmoi，可以用 template 依機器名稱切換；如果用 stow，可以把 monitors.lua 排除在 Git 外、每台機器手動寫。

輸入裝置配置

 1-- ~/.config/hypr/hyprland.lua 或拆到獨立檔案
 2
 3hl.config({
 4    input = {
 5        kb_layout = "us",
 6        -- 多語系：kb_layout = "us,de",
 7        -- 切換：kb_options = "grp:alt_shift_toggle",
 8        -- Caps Lock 當 Escape：kb_options = "caps:escape",
 9        kb_options = "",
10
11        follow_mouse = 1,         -- 焦點跟隨滑鼠
12        sensitivity = 0,          -- -1.0 到 1.0（0 = 不修改）
13        accel_profile = "flat",   -- flat 或 adaptive
14
15        repeat_rate = 25,         -- 長按時每秒重複幾次
16        repeat_delay = 600,       -- 按住多久開始重複（毫秒）
17
18        touchpad = {
19            natural_scroll = true,
20            disable_while_typing = true,
21            ["tap-to-click"] = true,
22            drag_lock = false,
23            scroll_factor = 1.0,
24        },
25    },
26})

可用的 XKB options 查詢：/usr/share/X11/xkb/rules/evdev.lst 或 localectl list-x11-keymap-options。

[VM 可測試] 鍵盤 layout、repeat rate。
[需實機測試] 觸控板設定、手勢、滑鼠靈敏度/加速曲線、多鍵盤配置。

Keybind 設計

修飾鍵（Modifier）：SUPER 是哪顆鍵

keybind 由「修飾鍵 + 按鍵」組成，Hyprland 配置裡最常當主修飾鍵的是 SUPER。SUPER 是 X11/Wayland 對 Meta 鍵的稱呼，在不同鍵盤上是不同的實體鍵：

• PC 鍵盤：Windows 鍵（⊞，通常在 Ctrl 與 Alt 之間）。
• Mac 鍵盤：Command 鍵（⌘）。

其他常見修飾鍵：SHIFT、CTRL（Control）、ALT（Mac 上是 Option ⌥）。組合寫法用空格串，例如 "SUPER SHIFT"。選 SUPER 當主修飾鍵是慣例——它幾乎不跟應用程式本身的快捷鍵衝突（應用多用 Ctrl / Alt）。

在 Mac 上跑虛擬機時，實體 ⌘ 會對應到 guest 的 SUPER，但 macOS 會先攔截部分 ⌘ 組合——這層 VM 專屬的坑見 VM 環境設定。

Bind 類型

Hyprland 提供多種 bind 函式，處理不同互動模式：

[VM 可測試] 所有 keybind 邏輯和配置語法。

基本操作

 1-- ~/.config/hypr/keybinds.lua
 2
 3-- 基本操作
 4hl.bind("SUPER", "Return", "exec", "kitty")
 5hl.bind("SUPER", "Q", "killactive")
 6hl.bind("SUPER", "D", "exec", "wofi --show drun")
 7hl.bind("SUPER", "F", "fullscreen", "0")
 8hl.bind("SUPER SHIFT", "Space", "togglefloating")
 9
10-- 焦點移動（vim 風格）
11hl.bind("SUPER", "H", "movefocus", "l")
12hl.bind("SUPER", "J", "movefocus", "d")
13hl.bind("SUPER", "K", "movefocus", "u")
14hl.bind("SUPER", "L", "movefocus", "r")
15
16-- 視窗移動
17hl.bind("SUPER SHIFT", "H", "movewindow", "l")
18hl.bind("SUPER SHIFT", "J", "movewindow", "d")
19hl.bind("SUPER SHIFT", "K", "movewindow", "u")
20hl.bind("SUPER SHIFT", "L", "movewindow", "r")
21
22-- 視窗大小調整（長按連續觸發）
23hl.binde("SUPER CTRL", "H", "resizeactive", "-20 0")
24hl.binde("SUPER CTRL", "J", "resizeactive", "0 20")
25hl.binde("SUPER CTRL", "K", "resizeactive", "0 -20")
26hl.binde("SUPER CTRL", "L", "resizeactive", "20 0")
27
28-- 滑鼠綁定：SUPER + 左鍵拖曳移動、右鍵拖曳調整大小
29hl.bindm("SUPER", "mouse:272", "movewindow")
30hl.bindm("SUPER", "mouse:273", "resizewindow")
31
32-- Workspace 切換
33hl.bind("SUPER", "1", "workspace", "1")
34hl.bind("SUPER", "2", "workspace", "2")
35hl.bind("SUPER", "3", "workspace", "3")
36hl.bind("SUPER", "4", "workspace", "4")
37hl.bind("SUPER", "5", "workspace", "5")
38hl.bind("SUPER", "6", "workspace", "6")
39hl.bind("SUPER", "7", "workspace", "7")
40hl.bind("SUPER", "8", "workspace", "8")
41hl.bind("SUPER", "9", "workspace", "9")
42
43-- 把視窗送到指定 workspace
44hl.bind("SUPER SHIFT", "1", "movetoworkspace", "1")
45hl.bind("SUPER SHIFT", "2", "movetoworkspace", "2")
46hl.bind("SUPER SHIFT", "3", "movetoworkspace", "3")
47-- 以此類推
48
49-- 螢幕截圖
50hl.bind("", "Print", "exec", "grimblast copy area")
51hl.bind("SUPER", "Print", "exec", "grimblast copy output")
52
53-- 多螢幕焦點切換
54hl.bind("SUPER", "comma", "focusmonitor", "l")
55hl.bind("SUPER", "period", "focusmonitor", "r")
56hl.bind("SUPER SHIFT", "comma", "movewindow", "mon:l")
57hl.bind("SUPER SHIFT", "period", "movewindow", "mon:r")

設計原則

• SUPER（Windows/Command 鍵）當 modifier，避免跟應用程式快捷鍵衝突
• 方向操作統一用 vim 的 HJKL，降低記憶負擔
• modifier 分層：SUPER 是焦點、SUPER+SHIFT 是移動、SUPER+CTRL 是調整大小
• 常用操作（開 terminal、關視窗、切 workspace）放在最順手的位置

Submap：模態快捷鍵

Submap 類似 vim 的模式切換——進入某個 submap 後，快捷鍵的意義改變，直到離開。適合需要連續操作的場景（如調整大小）：

 1-- 按 SUPER+R 進入 resize 模式
 2hl.bind("SUPER", "R", "submap", "resize")
 3
 4-- 定義 resize 模式的快捷鍵
 5hl.submap("resize")
 6hl.binde("", "H", "resizeactive", "-20 0")
 7hl.binde("", "L", "resizeactive", "20 0")
 8hl.binde("", "K", "resizeactive", "0 -20")
 9hl.binde("", "J", "resizeactive", "0 20")
10hl.bind("", "escape", "submap", "reset")   -- Escape 離開
11hl.submap("reset")

進入 resize 模式後，直接按 HJKL（不需要 modifier）就能持續調整大小，按 Escape 回到正常模式。

媒體鍵與硬體鍵

 1-- 音量（鎖屏時也能用、長按連續觸發）
 2hl.bindel("", "XF86AudioRaiseVolume", "exec", "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+")
 3hl.bindel("", "XF86AudioLowerVolume", "exec", "wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-")
 4hl.bindl("", "XF86AudioMute", "exec", "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle")
 5hl.bindl("", "XF86AudioMicMute", "exec", "wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle")
 6
 7-- 亮度
 8hl.bindel("", "XF86MonBrightnessUp", "exec", "brightnessctl s 10%+")
 9hl.bindel("", "XF86MonBrightnessDown", "exec", "brightnessctl s 10%-")
10
11-- 媒體播放
12hl.bindl("", "XF86AudioPlay", "exec", "playerctl play-pause")
13hl.bindl("", "XF86AudioNext", "exec", "playerctl next")
14hl.bindl("", "XF86AudioPrev", "exec", "playerctl previous")

[需實機測試] 媒體鍵（XF86Audio*）、亮度鍵（XF86MonBrightness*）、合蓋開關——這些依賴實體硬體送出正確的 keycode。VM 鍵盤通常沒有這些鍵。

環境變數

環境變數在 hl.config() 的 env 區段設定，影響 Hyprland 自身和其下執行的應用程式：

 1-- ~/.config/hypr/env.lua
 2
 3hl.config({
 4    env = {
 5        -- 游標主題
 6        "XCURSOR_SIZE, 24",
 7        "XCURSOR_THEME, Bibata-Modern-Classic",
 8        "HYPRCURSOR_SIZE, 24",
 9        "HYPRCURSOR_THEME, Bibata-Modern-Classic",
10
11        -- Qt 應用程式
12        "QT_AUTO_SCREEN_SCALE_FACTOR, 1",
13        "QT_QPA_PLATFORM, wayland;xcb",
14        "QT_QPA_PLATFORMTHEME, qt5ct",
15        "QT_WAYLAND_DISABLE_WINDOWDECORATION, 1",
16
17        -- GTK 應用程式
18        "GDK_BACKEND, wayland,x11,*",
19
20        -- XDG session
21        "XDG_CURRENT_DESKTOP, Hyprland",
22        "XDG_SESSION_TYPE, wayland",
23        "XDG_SESSION_DESKTOP, Hyprland",
24
25        -- Electron 應用程式（VS Code, Discord 等）
26        "ELECTRON_OZONE_PLATFORM_HINT, auto",
27
28        -- Firefox
29        "MOZ_ENABLE_WAYLAND, 1",
30    },
31})

NVIDIA 專用環境變數

如果使用 NVIDIA 顯卡，需要額外設定（AMD 和 Intel 不需要）：

 1-- 只在 NVIDIA 機器上加這些
 2hl.config({
 3    env = {
 4        "LIBVA_DRIVER_NAME, nvidia",
 5        "GBM_BACKEND, nvidia-drm",             -- Firefox 若崩潰就移除這行
 6        "__GLX_VENDOR_LIBRARY_NAME, nvidia",
 7        "NVD_BACKEND, direct",
 8    },
 9    cursor = {
10        no_hardware_cursors = true,             -- NVIDIA 常見的游標問題修正
11        allow_dumb_copy = true,
12    },
13})

[VM 不適用] NVIDIA 環境變數和驅動設定在 VM 裡無意義——VM 使用 virtio-gpu 或軟體渲染。這些設定只在實體 NVIDIA 機器上測試。

VM 專用環境變數

在 VM（UTM/QEMU）裡跑 Hyprland 需要額外的回退設定：

1-- 只在 VM 裡加，實機要移除
2hl.config({
3    env = {
4        "WLR_RENDERER_ALLOW_SOFTWARE, 1",
5        "LIBGL_ALWAYS_SOFTWARE, 1",
6        "WLR_NO_HARDWARE_CURSORS, 1",
7    },
8})

[已驗證] Hyprland 0.55（Aquamarine 渲染後端）+ UTM virtio-gpu-gl-pci 實測：使用 GPU 加速時不需要 WLR_RENDERER 或 LIBGL_ALWAYS_SOFTWARE，Hyprland 自動走 VirGL/Venus 硬體路徑。WLR_NO_HARDWARE_CURSORS 仍需要（virtio-gpu 不支援硬體 cursor）。完整 VM 設定見 VM 環境設定與測試矩陣。

journalctl：系統日誌的主要入口

systemd 的日誌系統（journal）集中收錄所有 service、kernel、user session 的 log。journalctl 是查詢這些日誌的指令。

基本用法

 1# 本次開機的所有日誌
 2journalctl -b
 3
 4# 本次開機的錯誤以上等級（err + crit + alert + emerg）
 5journalctl -b -p err
 6
 7# 本次開機，只看最後 50 行
 8journalctl -b -n 50
 9
10# 上一次開機的日誌（如果問題發生在上次開機、這次重開後想查）
11journalctl -b -1
12
13# 即時跟蹤新 log（類似 tail -f）
14journalctl -f

過濾特定來源

 1# 只看 Hyprland 相關
 2journalctl -b | grep -i hypr
 3
 4# 只看特定 systemd user unit
 5journalctl --user -u waybar -b
 6
 7# 只看 kernel 訊息（等同 dmesg）
 8journalctl -b -k
 9
10# 只看某個 process 的 log（用 PID）
11journalctl _PID=12345

時間範圍過濾

1# 最近 10 分鐘的 log
2journalctl --since "10 min ago"
3
4# 指定時間區間
5journalctl --since "2026-06-30 14:00" --until "2026-06-30 14:30"

dmesg：Kernel 層訊息

dmesg 顯示 kernel ring buffer 的內容——硬體偵測、driver 載入、硬體錯誤這些 kernel 層面的事件。排查 GPU driver 問題、USB 裝置問題、磁碟錯誤時需要看這裡。

 1# 所有 kernel 訊息（帶時間戳記）
 2dmesg -T
 3
 4# 只看錯誤和警告
 5dmesg -T --level=err,warn
 6
 7# GPU 相關（NVIDIA）
 8dmesg -T | grep -i nvidia
 9
10# GPU 相關（AMD）
11dmesg -T | grep -i amdgpu
12
13# USB 相關（鍵盤滑鼠突然不回應時看這裡）
14dmesg -T | grep -i usb

GPU driver 問題在 dmesg 裡的嚴重度差異很大：

一般 GPU hang（driver 嘗試自動恢復）：

1[  123.456] nvidia-modeset: ERROR: ...
2[  123.789] NVRM: Xid (PCI:0000:01:00): 79, pid=1234, ...
3[  124.000] amdgpu: GPU reset begin!
4[  124.500] amdgpu: GPU reset succeeded

NVIDIA 的 Xid 錯誤代碼表示不同類型的 GPU 錯誤。常見的 Xid 79 是 GPU fallback，Xid 31 是 GPU setup failure。完整代碼表可在 NVIDIA 官方文件搜尋「Xid Errors」。

硬體層級故障（嚴重，可能需要檢查硬體）：

1[  123.789] NVRM: Xid (PCI:0000:01:00): 79, pid=1234, GPU has fallen off the bus

GPU has fallen off the bus 表示 GPU 跟主機板的 PCIe 連線完全中斷。偶發一次可能是 driver 問題，反覆出現通常是硬體故障（PCIe 供電不足、顯卡接觸不良、過熱）。

hyprctl：Hyprland 的 Runtime 狀態查詢

hyprctl 是 Hyprland 提供的命令列控制工具，可以在 compositor 運行中查詢狀態和執行操作。只有在 Hyprland 正在跑的時候才能使用。

 1# 目前所有視窗的資訊
 2hyprctl clients
 3
 4# 目前的 monitor 設定
 5hyprctl monitors
 6
 7# 目前的 workspace 資訊
 8hyprctl workspaces
 9
10# Hyprland 版本和 build 資訊
11hyprctl version
12
13# 重新載入 config（不重啟 compositor）
14hyprctl reload
15
16# 查看上一次 config reload 是否有錯誤
17hyprctl systeminfo

hyprctl reload 是測試 config 變更的安全方式。如果 config 有語法錯誤，reload 會報錯但 compositor 繼續用舊 config 跑，不會崩潰。

systemctl：Service 狀態管理

桌面環境的工具（waybar、mako 等）如果用 systemd user unit 管理，可以用 systemctl --user 查看狀態和重啟。

 1# 查看某個 user service 的狀態
 2systemctl --user status waybar
 3
 4# 輸出範例：
 5# waybar.service - Highly customizable Wayland bar
 6#    Loaded: loaded (/usr/lib/systemd/user/waybar.service; enabled)
 7#    Active: active (running) since Mon 2026-06-30 10:00:00 CST
 8#    Main PID: 1234 (waybar)
 9
10# 重啟
11systemctl --user restart waybar
12
13# 看最近的 log
14systemctl --user status waybar -n 20

如果這些工具不是 systemd unit（在 Hyprland config 裡用 exec-once 啟動的），就不能用 systemctl 管理。改用 pgrep 和 kill：

1pgrep waybar      # 查看是否在跑
2killall waybar    # 停止
3waybar &          # 背景啟動

即時資源監控

排查效能問題和記憶體耗盡時，需要看即時的系統資源使用情況。

htop：互動式 process 監控。按 M 可以按記憶體用量排序，按 P 按 CPU 排序。找到佔用異常的 process 後按 F9 可以直接 kill。

btop：功能更豐富的替代品，顯示 CPU、記憶體、磁碟、網路的即時使用情況，圖形化介面比 htop 直觀。

1# 安裝
2sudo pacman -S btop    # Arch
3sudo apt install btop  # Debian/Ubuntu
4
5# 執行
6btop

nvidia-smi：NVIDIA GPU 的專屬監控工具。顯示 GPU 使用率、記憶體、溫度、跑在上面的 process。

1# 一次性查看
2nvidia-smi
3
4# 持續監控（每 2 秒更新）
5nvidia-smi -l 2

常見 Log Pattern 速查

排查流程

這篇是 Hyprland 桌面的具體日誌工具；背後「先讀權威狀態、不靠肉眼猜」的通用診斷心法（每種問題的權威來源、四步流程），見 Linux 除錯與診斷：診斷心法。遇到桌面環境問題時的判讀順序：

1. 判斷影響範圍：只有一個視窗壞了、某個工具壞了、整個桌面壞了、還是系統完全不回應？影響範圍決定要看哪一層的 log。

2. 看 journalctl：journalctl -b -p err 先看本次開機有沒有錯誤等級的訊息。大部分 userspace 的問題（compositor crash、工具 crash）會出現在這裡。

3. 看 dmesg：如果 journalctl 沒有明顯線索、或症狀跟硬體有關（畫面凍結、USB 不回應），dmesg -T --level=err,warn 看 kernel 層有沒有硬體或 driver 錯誤。

4. 查特定工具的狀態：systemctl --user status <tool> 或 pgrep <tool> 確認工具是否還活著。如果死了，看它最後的 log 訊息。

5. 即時監控：如果問題是漸進式的（越來越慢、偶爾卡頓），開 btop 或 htop 觀察 CPU 和記憶體的即時趨勢，找出佔用異常的 process。

找到問題後的下一步

判讀完 log 確認問題類型後，行動路徑依問題性質分流：

• Config 錯誤：直接修 config，用 hyprctl reload 或重啟工具驗證。操作步驟見常見故障場景與恢復操作。
• 軟體 bug（segfault、特定操作觸發 crash）：到該軟體的 issue tracker（通常在 GitHub）搜尋錯誤訊息。Hyprland 的 issue tracker 在 github.com/hyprwm/Hyprland。回報 bug 時附上 hyprctl systeminfo 的輸出和相關的 journalctl log。
• GPU driver 問題：NVIDIA 用戶檢查是否有更新的 driver 版本（pacman -Syu nvidia）。AMD 用戶的 driver 跟 kernel 綁定，更新 kernel 就更新 driver（pacman -Syu linux）。
• 硬體故障（GPU has fallen off the bus 反覆出現）：軟體層面無法解決，需要檢查硬體（PCIe 插槽接觸、供電、溫度）。

Caelestia 提供的元件

手動拼裝的桌面需要 6-8 個獨立工具各自配置。Caelestia 把這些元件用 Quickshell 統一實作：

Quickshell 框架

Quickshell 是一個 Qt6/QML 的 shell framework，用來在 Wayland compositor 上渲染 UI 元件。它的角色是 Caelestia 跟 Hyprland 之間的中介層：

• 用 QML（Qt 的宣告式 UI 語言）描述介面元件
• 透過 wlr-layer-shell 協議把元件渲染成 Wayland layer surface（這是狀態列、啟動器能「黏在」螢幕邊緣的原因）
• 直接存取 Hyprland IPC，可以即時讀取工作區狀態、視窗資訊
• 配置檔修改後自動 reload，不需要重啟

跟其他桌面 shell 框架的差異主要在底層渲染引擎和配置語言。

跟 AGS / Eww 的比較

選型判讀：想要開箱即用的華麗桌面 → Caelestia（Quickshell）。想要自己一個個拼、有前端經驗 → AGS。想要最簡單輕量 → Eww。想要完全控制每個細節 → 手動拼裝 waybar + wofi + mako。

跟手動拼裝的 Trade-off

Caelestia 的優勢是省去「挑工具 + 各自配置 + 統一視覺風格」的大量前期功夫。Material Design 3 的動態取色（從桌布自動提取配色方案套用到所有元件）是手動拼裝很難做到的。

代價是兩個：

第一，鎖定在 Caelestia 的設計決策裡。你可以調配色、改模組顯示、換桌布，但桌面的整體結構和行為邏輯是 Caelestia 決定的。想要「狀態列放底部 + 用不同的 launcher」這種結構性改動，比手動拼裝困難得多。

第二，穩定性風險。Caelestia 的 README 明確寫：「Configs, and internal tokens used in them, may be changed or removed without notice」。這表示一次更新可能靜默破壞你的自訂設定。這跟 Hyprland 本身的 breaking changes 疊加，等於你的桌面有兩層快速移動的依賴。

三個 GitHub Repo 的分工

完整安裝（caelestia install）會同時部署三者。也可以只裝 shell（caelestia-shell AUR package），保留自己的 Hyprland config 和應用程式設定。

定位認知

Caelestia 的本質是一套社群維護的 rice dotfiles，不是有 release cycle 和 backward compatibility 承諾的軟體產品。用它的心態應該接近「fork 別人的 dotfiles 來改」而不是「安裝一個桌面環境」。這個定位決定了它適合什麼人：享受折騰和客製化的人會從中得到很好的起點，想要穩定日用的人應該考慮 GNOME 或 KDE Plasma。

X11（X Window System）是用了三十多年的傳統協議。成熟、穩定、所有工具都支援。設計上的根本問題是安全性——任何 X11 應用程式都能讀取其他視窗的內容和鍵盤輸入，這是協議層的限制，不是 bug。

Wayland 是設計來取代 X11 的新協議。每個應用程式只看得到自己的視窗、效能更好、對現代硬體的支援更完整。多數主流發行版已經把 Wayland 設為預設，但部分老舊應用程式和特殊需求（某些螢幕錄製、遠端桌面工具）的支援還在追趕中，這些情境會透過 XWayland（相容層）跑 X11 應用程式。

新的 tiling WM 主要基於 Wayland 開發，X11 上的老牌（i3, bspwm, dwm）仍然活躍但不再是未來方向。

主流 Tiling WM

i3（X11）/ sway（Wayland） 是社群最大、文件最齊全、行為最可預測的選擇。i3 跑在 X11 上，sway 是它的 Wayland 移植，配置格式幾乎相同。配置檔用自己的語法，直覺的 key = action 對應。

1# sway/config 片段
2set $mod Mod4
3bindsym $mod+h focus left
4bindsym $mod+j focus down
5bindsym $mod+k focus up
6bindsym $mod+l focus right
7bindsym $mod+Shift+h move left
8bindsym $mod+1 workspace number 1
9bindsym $mod+2 workspace number 2

穩定性是 i3/sway 最大的賣點——配置寫好之後很少因為更新而壞掉。適合想要可靠的平鋪工作流、不需要華麗視覺效果的人。

Hyprland（Wayland） 吸引的是在意桌面視覺品質的平鋪使用者——看 r/unixporn 的 Hyprland 截圖就知道，流暢的視窗切換動畫、圓角、視窗模糊、漸層邊框，這些傳統 tiling WM 社群視為不必要的裝飾，Hyprland 做成內建功能並且認真打磨。配置檔改完即時生效（hot reload），迭代調教的回饋循環很短。

這份視覺投入換來的 trade-off 是穩定性。開發節奏快意味著偶爾會有 breaking changes——某次更新後配置語法改了（2026 年 4 月的 Lua 遷移就是一例）、某個選項改名或移除。把它當主力桌面，要有「更新後可能要回來調配置」的心理準備。Hyprland 配置會詳細講它的設定。

bspwm（X11） 是純粹的 BSP 樹狀分割。它只做一件事：管理視窗的樹狀結構。所有操作透過 bspc 命令列工具驅動，快捷鍵綁定交給 sxhkd（一個獨立的快捷鍵 daemon）。UNIX 哲學——每個工具只做一件事，組合起來用。

dwm（X11） 極簡到配置要改 C 原始碼然後重新編譯。不是給「想要方便配置」的人用的，而是給「想要完全理解自己桌面每一行程式碼」的人用的。

拼裝式桌面的代價

Linux tiling WM 的桌面是你自己拼出來的：compositor（Hyprland/sway）負責視窗管理、狀態列（waybar）負責頂部資訊條、啟動器（rofi/wofi）負責 app 搜尋啟動、通知（mako/dunst）負責通知彈窗、鎖屏另外裝。每一塊是不同專案、不同作者。

好處是每一塊都可以換。壞處是當某件事壞了，你要自己判斷是哪一層的問題。藍牙選單不能點？可能是狀態列的 module 設定錯、可能是 blueman 沒跑、可能是 D-Bus session 有問題。完整桌面環境（KDE/GNOME）幫你整合測試過了，拼裝式桌面沒有這層保障。

多螢幕的處理

多螢幕是自動平鋪比較能展現價值的場景。每個螢幕是獨立的平鋪區域，視窗在哪個螢幕就在那個螢幕的範圍內平鋪。

快捷鍵跨螢幕操作是標配功能：把焦點跳到另一個螢幕、把當前視窗丟到另一個螢幕（丟過去後自動融入那邊的平鋪佈局）。三螢幕時這個便利性比單螢幕更明顯——純滑鼠拖視窗跨螢幕需要的移動距離很長。

工作區跟螢幕的綁定方式是各工具差異最大的地方。

macOS 的 Spaces 是綁定螢幕的——每個螢幕有自己獨立的一組 Spaces。yabai 沿用這個行為，切換工作區時只影響當前螢幕。AeroSpace 用自己的虛擬工作區繞過 macOS 原生 Spaces 的限制，多螢幕操作被普遍認為更穩定、更直覺。

Hyprland 的 workspace 可以動態指派到不同螢幕——workspace 3 現在在螢幕 A，你可以把它移到螢幕 B。這種模型彈性最大，但也需要清楚的心智模型來管理「哪個 workspace 在哪」。

熱插拔螢幕（接上、拔掉外接螢幕）是各工具的常見痛點。拔掉螢幕時，該螢幕上的視窗要搬到剩餘螢幕重新平鋪；插上螢幕時，佈局要擴展。多數工具有對應設定（記住螢幕配置、自動還原佈局），但體驗不見得完美，偶爾需要手動整理。

Dotfile 中的視窗管理配置

視窗管理是 dotfile 管理裡「桌面層」的核心。WM 配置檔決定了整個桌面的操作邏輯——快捷鍵怎麼綁、視窗間距多大、哪些 app 要浮動、工作區怎麼分配。

macOS 工具的配置檔通常是一個檔案：AeroSpace 的 ~/.aerospace.toml、yabai 的 ~/.yabairc + ~/.skhdrc、Amethyst 的 ~/.amethyst.yml。把這些檔案放進 dotfile repo，換 Mac 時就能還原整套視窗管理行為。

Linux tiling WM 的配置在 ~/.config/ 下，通常是一個資料夾：Hyprland 的 ~/.config/hypr/、sway 的 ~/.config/sway/、i3 的 ~/.config/i3/。除了 WM 本身，狀態列（waybar 的 ~/.config/waybar/）、啟動器（rofi 的 ~/.config/rofi/）、通知（mako 的 ~/.config/mako/）等周邊元件的配置也各自有檔案。一套完整的 Linux 平鋪桌面，dotfile repo 裡可能會有十幾個配置目錄——這也是為什麼 Linux 桌面客製化社群那麼依賴 dotfile 管理工具（見管理工具與目錄結構）。

跟螢幕硬體綁定的設定（螢幕解析度、縮放比、螢幕排列順序）通常也寫在 WM 配置裡。這部分在跨機器搬移 dotfile 時需要調整——同一份 Hyprland 配置裡的 monitor 設定，在筆電上是一個螢幕、在桌機上可能是三個。常見做法是把硬體相關設定拆到單獨檔案（如 monitors.lua），主配置用 require 引入，這樣跨機器時只需要替換這一個檔案。同步與環境重建會講跨機器搬移時怎麼處理這類硬體差異。

Workspace 設定

Workspace 是平鋪式桌面的空間管理單位。Hyprland 的 workspace 是動態的——不需要預先定義多少個，按了不存在的 workspace 編號就會自動建立。

 1-- 把特定 workspace 綁定到特定螢幕
 2hl.config({
 3    workspace = {
 4        "1, monitor:DP-1, default:true",
 5        "2, monitor:DP-1",
 6        "3, monitor:DP-1",
 7        "7, monitor:HDMI-A-1, default:true",
 8        "8, monitor:HDMI-A-1",
 9        "9, monitor:HDMI-A-1",
10    },
11})

常見的使用模式：

• Workspace 1-3 放在主螢幕（寫程式用）
• Workspace 7-9 放在副螢幕（瀏覽器、通訊軟體、監控）
• 用鍵盤瞬間切換（SUPER + 數字鍵），比 alt-tab 在一堆視窗裡找快

Per-workspace layout 覆寫

1hl.config({
2    workspace = {
3        "1, layoutopt:orientation:left",     -- workspace 1 用左側 master
4        "2, layoutopt:orientation:top",      -- workspace 2 用頂部 master
5    },
6})

[VM 可測試] Workspace 切換、綁定邏輯、per-workspace layout。
[需實機測試] Workspace 綁定到特定實體螢幕的行為。

Window Rules

Window rules 讓特定應用程式在開啟時自動套用設定——指定 workspace、強制浮動、設定大小等。

 1hl.config({
 2    windowrule = {
 3        -- 特定 app 自動送到指定 workspace
 4        "workspace 8, class:^(firefox)$",
 5        "workspace 9, class:^(Slack)$",
 6
 7        -- 設定面板、對話框等維持浮動（不進平鋪）
 8        "float, class:^(pavucontrol)$",
 9        "float, class:^(nm-connection-editor)$",
10        "float, title:^(Open File)$",
11        "float, title:^(Save As)$",
12
13        -- Picture-in-picture 浮動 + 置頂 + 固定大小
14        "float, title:^(Picture-in-Picture)$",
15        "pin, title:^(Picture-in-Picture)$",
16        "size 480 270, title:^(Picture-in-Picture)$",
17        "move 100%-490 50, title:^(Picture-in-Picture)$",
18
19        -- 視窗透明度（active inactive）
20        "opacity 0.9, class:^(kitty)$",
21        "opacity 0.85 0.75, class:^(Code)$",
22
23        -- 防止 Electron app 自動最大化
24        "suppressevent maximize, class:.*",
25
26        -- XWayland video bridge（螢幕分享用）
27        "opacity 0.0 override, class:^(xwaylandvideobridge)$",
28        "noanim, class:^(xwaylandvideobridge)$",
29        "noinitialfocus, class:^(xwaylandvideobridge)$",
30        "maxsize 1 1, class:^(xwaylandvideobridge)$",
31        "noblur, class:^(xwaylandvideobridge)$",
32    },
33})

查詢應用程式的 class 和 title

1hyprctl clients          # 列出所有開啟的視窗（含 class、title、PID 等）
2hyprctl activewindow     # 當前焦點視窗的資訊

Window rules 用 regex 匹配 class 和 title。靜態 rules 匹配的是視窗開啟時的初始值（initialTitle / initialClass）。

Window rules 是讓平鋪式桌面「不只是把所有東西硬塞格子」的關鍵——識別哪些 app 適合浮動、哪些適合指定位置，需要累積使用經驗。

[VM 可測試] Window rules 邏輯、workspace 指派、float 規則。查 class/title 也在 VM 裡能做。

Layout 配置

Dwindle

每個新視窗把當前區域一分為二（螺旋式切分），適合不固定視窗數量的工作流：

1hl.config({
2    dwindle = {
3        pseudotile = true,       -- 允許 app 請求 pseudo-tiling（保留原始大小）
4        preserve_split = true,   -- 不自動改變分割方向
5        force_split = 2,         -- 0=跟隨滑鼠, 1=永遠左/上, 2=永遠右/下
6        smart_split = false,
7        smart_resizing = true,
8    },
9})

Master

一個主區域 + 其餘視窗堆疊在側邊，適合「一個主力視窗 + 多個參考視窗」的模式：

1hl.config({
2    master = {
3        new_on_top = false,       -- 新視窗放 master 還是 stack
4        orientation = "left",     -- master 區域位置：left / right / top / bottom / center
5        mfact = 0.55,             -- master 區域佔螢幕的比例
6    },
7})

在 general 裡設定預設 layout：

1hl.config({
2    general = {
3        layout = "dwindle",       -- 或 "master"
4    },
5})

[VM 可測試] Layout 切換和參數調整的行為邏輯。

外觀設定

 1hl.config({
 2    general = {
 3        gaps_in = 5,
 4        gaps_out = 10,
 5        border_size = 2,
 6        ["col.active_border"] = "rgba(89b4faee) rgba(cba6f7ee) 45deg",
 7        ["col.inactive_border"] = "rgba(313244aa)",
 8    },
 9    decoration = {
10        rounding = 8,
11
12        blur = {
13            enabled = true,
14            size = 5,             -- 模糊半徑（越高越模糊、越吃 GPU）
15            passes = 2,           -- 模糊次數（越多越平滑、越重）
16            vibrancy = 0.17,
17            noise = 0.02,
18            new_optimizations = true,
19        },
20
21        shadow = {
22            enabled = true,
23            range = 15,
24            render_power = 3,     -- 1-4，衰減曲線
25            color = "0xee1a1a2e",
26        },
27
28        dim_inactive = false,
29        dim_strength = 0.2,
30
31        active_opacity = 1.0,
32        inactive_opacity = 0.95,
33    },
34})

[需實機測試] blur 的效能影響和視覺品質——這是 Hyprland 最吃 GPU 的功能。VM 裡建議 blur = { enabled = false } 避免卡頓。shadow 和 rounding 在軟體渲染下可以動但會很慢。

動畫設定

 1-- 定義 bezier 曲線
 2hl.animation("bezier", "ease", 0.25, 0.1, 0.25, 1)
 3hl.animation("bezier", "overshot", 0.05, 0.9, 0.1, 1.05)
 4
 5-- Spring 物理動畫（較新的替代方案）
 6hl.animation("spring", "bouncy", 1, 8, 0)   -- damping, frequency, speed
 7
 8-- 套用動畫
 9hl.animation("animation", "windows", 1, 4, "ease", "slide")
10hl.animation("animation", "windowsOut", 1, 4, "ease", "popin 80%")
11hl.animation("animation", "fade", 1, 3, "ease")
12hl.animation("animation", "workspaces", 1, 4, "ease", "slide")
13
14-- 關閉特定動畫
15hl.animation("animation", "windowsMove", 0)

VM 裡跑 Hyprland 時，建議完全關閉動畫以維持可用的操作速度：

1hl.config({
2    animations = {
3        enabled = false,
4    },
5})

[需實機測試] 動畫流暢度是 Hyprland 的核心賣點，只有實機能評估。VM 裡的卡頓是 GPU 加速不足造成的，不代表 Hyprland 本身的效能。

Autostart

 1hl.config({
 2    exec_once = {
 3        -- 桌面元件
 4        "waybar",
 5        "mako",
 6        "hyprpaper",
 7
 8        -- 系統服務
 9        "/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1",
10        "wl-paste --type text --watch cliphist store",
11
12        -- Idle daemon（閒置鎖屏，鎖屏安全模型見 session-lock 卡）
13        "hypridle",
14    },
15})

exec_once 只在 Hyprland 啟動時跑一次（config reload 不會重複執行）。如果需要每次 reload 都重跑某個指令，用 exec（但多數情況不需要）。

Plugin 系統

Hyprland 用 hyprpm（Hyprland Plugin Manager）管理 plugin：

1hyprpm update                                              # 更新 plugin index
2hyprpm add https://github.com/hyprwm/hyprland-plugins     # 加入官方 plugin repo
3hyprpm enable hyprexpo                                     # 啟用 plugin
4hyprpm disable hyprexpo                                    # 停用 plugin
5hyprpm list                                                # 列出可用 plugin

Plugin 的配置寫在 hyprland.lua 裡，是 dotfile 的一部分。

[VM 可測試] 不依賴 GPU 的 plugin（hy3、hyprbars）。
[需實機測試] 視覺特效類 plugin（hyprexpo、hyprspace、hyprtrails）。

Dotfile 結構對應

Hyprland 的配置拆成多個 .lua 檔，全部放在同一個 stow package 裡。monitors.lua 是硬體相關的——跨機器搬移時可能要排除或用 template/local 機制處理（見跨平台共用一個 Repo）：

 1~/dotfiles/
 2└── hyprland/
 3    └── .config/
 4        └── hypr/
 5            ├── hyprland.lua       # 主入口（只有 require 行）
 6            ├── monitors.lua       # 硬體相關、可能排除或 template
 7            ├── keybinds.lua
 8            ├── rules.lua
 9            ├── autostart.lua
10            ├── appearance.lua
11            └── env.lua

穩定性與維護的務實面

Hyprland 的開發節奏快、功能更新激進。v0.55 的 Lua 遷移就是一個典型案例——配置格式整個換掉，舊的 .conf 只會再支援一到兩個版本。配置檔的語法和可用選項會隨版本變動。

應對策略：

• 更新前先看 Hyprland wiki 的 Configuring 頁面和 changelog
• dotfile repo 的 commit message 記錄「因應 Hyprland vX.Y 改了什麼設定」
• 如果用 Arch 的 rolling release，pacman -Syu 前先確認 Hyprland 是否有 breaking change（Arch 社群通常會在論壇預警）
• 官方提供遷移工具（如 hyprlang2lua），格式變更時優先使用

這是視窗管理與平鋪式工作流提過的代價——把日常桌面建立在高速移動的專案上，持續的配置維護是實際成本。

VM 與實機測試對照

前提條件

• Arch Linux（或 Arch 系發行版如 CachyOS、EndeavourOS）
• Hyprland 已安裝且能從 TTY 啟動（見 Hyprland 安裝指南）
• AUR helper 已安裝（yay 或 paru）
• 網路連線（安裝過程需要拉 AUR 套件和 Git repo）

推薦方式：CLI 完整安裝

1paru -S caelestia-cli
2caelestia install

caelestia install 做的事：

1. 從 GitHub clone Caelestia dotfiles repo
2. 安裝所有 runtime 依賴（透過 AUR helper）
3. 部署配置檔到 ~/.config/ 對應位置
4. 設定 Hyprland 載入 Caelestia shell

安裝完成後重新啟動 Hyprland，Caelestia 會自動載入。

注意：caelestia install 會覆寫你現有的 Hyprland 配置。如果你已經有自己的 hyprland.conf / hyprland.lua，先備份。安裝後可以透過 ~/.config/caelestia/hypr-user.lua 加入自訂設定。

Shell-only 安裝

只裝 UI 元件，不動 Hyprland config 和其他應用程式設定：

1yay -S caelestia-shell

啟動方式：

1caelestia shell -d    # daemonized，背景執行
2# 或
3qs -c caelestia       # 透過 quickshell 直接啟動

Shell 不會因為裝了就自動啟動——Hyprland 開機只執行 config 裡 exec-once 列出的程式，漏列的結果是登入後桌面沒有 bar 也沒有通知（實測：手動啟動用了幾天、直到主機重開才暴露從沒進 autostart）。把啟動指令加進 hyprland.conf：

1exec-once = caelestia shell -d

Caelestia 自帶 bar、通知、鎖屏與 launcher，跟獨立的 waybar / mako 互斥：通知的 D-Bus name（org.freedesktop.Notifications）同一時間只有一個擁有者、bar 會疊兩條。設 Caelestia 為主 shell 時，把 waybar / mako 從 exec-once 移除（註解掉可留作停用 Caelestia 時的 fallback）。

AUR 套件一覽

caelestia-shell 是 caelestia-cli 的 optional dependency（提供 shell 控制與截圖功能）——只裝 CLI 不會自動拉 shell，兩個都要就各自明講：yay -S caelestia-cli caelestia-shell（實測 caelestia-cli 1.1.1 的 PKGBUILD，shell 列在 optdepends）。

手動 Build

從原始碼 build shell（不使用 AUR）：

1cd "$XDG_CONFIG_HOME/quickshell"
2git clone https://github.com/caelestia-dots/shell.git caelestia
3cd caelestia
4cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/
5cmake --build build
6sudo cmake --install build

Runtime 依賴

Shell 依賴

quickshell-git 是硬性需求。穩定版的 quickshell 缺少 Caelestia 需要的 API，安裝穩定版會導致 shell 無法啟動。

CLI 依賴

登入管理器

Caelestia 不含登入管理器。推薦用 greetd + tuigreet：

1sudo pacman -S greetd greetd-tuigreet

/etc/greetd/config.toml：

1[terminal]
2vt = 1
3
4[default_session]
5command = "tuigreet --cmd Hyprland"
6user = "greeter"

1sudo systemctl enable greetd

也可以不裝登入管理器，直接從 TTY 啟動：

1# 登入 TTY 後
2Hyprland

Full Dotfiles 管理範圍

caelestia install 部署的完整 dotfiles 不只是 shell，還包括：

• Hyprland config（Lua 格式）
• Firefox / Zen Browser 設定
• VSCode / Zed 設定
• Fish shell config
• Foot terminal config
• Starship prompt
• Btop
• Fastfetch
• Thunar 檔案管理器

這是 Caelestia 「一套 rice」的完整範圍。如果你只想用 shell 元件、保留自己的應用程式配置，用 shell-only 安裝。

CLI 常用指令

首次啟動常見問題

黑屏：通常是缺少 xdg-desktop-portal-hyprland。確認已安裝：

1pacman -Q xdg-desktop-portal-hyprland

Shell 沒有載入：確認 quickshell-git（不是 quickshell 穩定版）已安裝，且 Hyprland 的 exec-once 有啟動 Caelestia。

字型 icon 顯示為方塊：缺少 Material Symbols 和 Nerd Font。安裝：

1yay -S material-symbols ttf-caskaydia-cove-nerd

VM 測試 vs 實機測試

VM 可測試：安裝流程完整性、CLI 指令是否正常、配置檔結構和語法、啟動器功能、通知系統行為、配置 reload。

需實機測試：動畫流暢度和幀率、blur 品質和效能影響、Material Design 3 動態取色品質、多螢幕佈局、daily-use 的回應速度和穩定性。

VM 中 Caelestia 的 blur、動畫、動態取色會極度降級或無法運作（軟體渲染沒有足夠的 GPU 加速）。VM 適合驗證「裝得起來、config 能讀」，不適合評估視覺效果和日常使用體驗。

UTM on Apple Silicon 設定

Apple Silicon Mac 用 UTM（基於 QEMU）跑 ARM64 Linux VM：

• CPU：UTM 使用 Apple Hypervisor.framework，ARM64 guest 接近原生速度
• GPU：使用 virtio-gpu-gl-pci（UTM v4.1+ 新建 Linux VM 的預設）。UTM v5.0.0+ 的 GitHub release 版支援 Venus driver（guest Mesa → host MoltenVK → Apple Metal 的 Vulkan 轉送路徑），這是目前最好的 GPU 加速方案
• Linux ISO：Arch Linux ARM（archlinuxarm.org）或 Fedora aarch64
• 建議配置：4 CPU cores、4GB+ RAM、40GB+ disk

UTM 建 VM 的注意事項

• 第一頁選 Virtualize，不是 Emulate——同架構（Apple Silicon 跑 ARM64 guest）兩條都是 QEMU，差在 Virtualize 走 hvf 硬體虛擬化（CPU 接近原生）、Emulate 走 TCG 純軟體模擬（CPU 慢一個數量級；實測 C++ 大型編譯一小時只跑 1/3）。Emulate 只在跨架構（ARM Mac 跑 x86_64 guest）才需要。判別現有 VM：guest 裡 lscpu 的 Model name 是 - 為直通、顯示具體型號（如 Cortex-A72）為模擬
• 選 「Linux」 虛擬機類型，不是 「Other」
• Display Card 選 virtio-gpu-gl-pci（有 3D 加速），不是 virtio-gpu-pci（無加速）；Emulate 精靈預設給無加速的 virtio-gpu-pci、Virtualize 精靈通常直接給對
• VM 視窗可能停在序列視圖、圖形顯示是另一個視圖——Virtualize 精靈預設多附一個序列裝置，UTM 視窗開機後可能顯示的是序列 console（文字登入、guest 裡 who 顯示登入在 pts/0），跟 virtio-gpu 的圖形輸出是兩個獨立視圖。切換：VM 視窗工具列的顯示器下拉選單 → 選 Display 1 (virtio-gpu)。判讀圖形裝置本身有沒有掛上看 guest 的 ls /dev/dri/（有 card0 = 裝置在、只是視窗看錯視圖）。不想每次切就到 VM 設定移除序列裝置。compositor 要在圖形視圖那側的 VT 上啟動、序列 console 起不了 Hyprland
• 如果用 App Store 版的 UTM（不含 Venus），只有基本的 virtio-gpu-gl 加速
• GitHub release 版的 UTM 支援 Venus/MoltenVK，效能更好但仍不及裸金屬
• 修飾鍵：Mac 的 ⌘ 對應 guest 的 SUPER，但 macOS 會先攔截部分 ⌘ 組合——Hyprland 的 keybind 幾乎都以 SUPER（Meta）當主修飾鍵（見 核心配置的修飾鍵段），而 UTM 裡 Mac 的 Command ⌘ 通常就是那顆 SUPER。問題是 macOS 自己會先吃掉某些 ⌘ 組合（⌘+Q 結束 app、⌘+Space Spotlight…），VM 收不到。判讀：SUPER 綁定沒反應、但焦點視窗打字正常，多半是宿主層攔截、不是 Hyprland 配置錯。解法：先確認 VM 視窗有 focus；在 UTM 的鍵盤/輸入設定開「把系統快捷鍵送進 VM（capture input）」讓 ⌘ 組合進 guest。臨時繞過：需要重載配置這類動作，直接在已開的終端機下指令（如 source / hyprctl reload），不必卡在 ⌘ 鍵上

VM 必要環境變數

在 Hyprland 配置裡加入以下環境變數（只在 VM 中使用，實機要移除）：

1-- VM-only environment variables
2env = {
3    "WLR_RENDERER_ALLOW_SOFTWARE, 1",  -- 允許軟體渲染 fallback
4    "WLR_NO_HARDWARE_CURSORS, 1",      -- 停用硬體 cursor（VM 常見問題）
5    "LIBGL_ALWAYS_SOFTWARE, 1",        -- 強制 Mesa 軟體渲染
6}

如果上述仍無法啟動（virtio-gpu vGPU passthrough 的情況）：

1env = {
2    "AQ_NO_KMS_REQUIREMENT, 1",       -- 繞過 KMS 需求
3    "WLR_RENDERER, pixman",            -- 強制 pixman 軟體 renderer
4}

[已驗證] Hyprland 0.55（Aquamarine）+ UTM virtio-gpu-gl-pci 實測：GPU 加速模式下 Hyprland 直接走 VirGL/Venus，不需要 WLR_RENDERER 或 WLR_RENDERER_ALLOW_SOFTWARE。AQ_NO_KMS_REQUIREMENT 仍有效。軟體渲染 fallback 路徑（WLR_RENDERER=pixman）未測試——有 GPU 加速時不需要走這條。

VM 中應該關閉的效果

軟體渲染下，視覺效果是最大的效能殺手。建議在 VM 配置中停用：

 1hl.config({
 2    decoration = {
 3        blur = { enabled = false },     -- 模糊是 GPU 最重的效果
 4        shadow = { enabled = false },
 5        rounding = 0,
 6    },
 7    animations = {
 8        enabled = false,                -- 或設定極簡動畫
 9    },
10})

這些效果關閉後，基本的平鋪操作（切換視窗、移動 workspace、開關 app）在 VM 中應該足夠流暢。

效能預期

VM 的價值在於驗證配置邏輯，不在於評估視覺體驗。如果在 VM 裡覺得「卡」，不代表 Hyprland 本身慢——多數情況是 VM 圖形加速的限制。

Sway 作為 VM 初步驗證工具

如果 VM 中 Hyprland 跑得太吃力，可以先用 Sway 驗證 VM 的 Wayland 圖形棧是否正常：

1sudo pacman -S sway foot
2sway

Sway 比 Hyprland 輕量（基於 wlroots、沒有華麗動畫），如果 Sway 能跑，代表 VM 的 Wayland 環境是正常的，Hyprland 的問題只是效能不夠。如果連 Sway 都跑不動，要回去檢查 VM 的 GPU 設定。

VM vs 實機測試矩陣

VM 中可完整驗證

需要實機測試

務實的 VM 使用策略

VM 階段的目標是「把配置寫好、驗證邏輯、確認 bootstrap script 能跑」，不是「體驗 Hyprland 好不好用」。具體做法：

1. 在 VM 中完成 Arch Linux 安裝 + Hyprland 套件安裝（怎麼把那台 Linux 從 ISO 裝起來、安裝程式選項怎麼判讀、裝完怎麼驗工具與連入，見 Linux 安裝與機器初始化）
2. 關閉所有視覺效果（blur / animation / shadow）
3. 寫好完整的 Hyprland 配置（keybind / rules / workspace / autostart）
4. 寫好 waybar / wofi / mako 配置
5. 測試 stow 部署流程（從 dotfile repo clone → stow → 配置生效）
6. 測試 bootstrap script（install.sh 從零到完整桌面）
7. 把驗證過的配置 commit 進 dotfile repo

到實機時，clone dotfile repo → 跑 install.sh → 補上硬體相關設定（monitor、GPU 驅動、觸控板）→ 打開視覺效果。VM 階段的工作在實機上幾乎不用重做。

章節文章

macOS 讀者的主線是前兩篇（浮動 vs 平鋪、macOS 工具鏈）。Linux Tiling WM 生態和 Wayland 顯示協議是想在 VM 或實機上體驗 Linux 桌面的選讀——macOS 上用 AeroSpace 或 yabai 的讀者可以直接跳到同步與 Bootstrap。

跨分類引用

• → 模組五：Hyprland 配置：Hyprland 的完整配置實務
• → 模組六：桌面 Rice 設計：compositor 之上的狀態列、啟動器、通知、配色系統
• → 模組一：管理工具與目錄結構：WM 配置怎麼進 dotfile repo
• → 模組八：同步、Bootstrap 與環境重建：跨機器搬移時硬體相關設定怎麼處理

配置檔路徑

shell.json 不會在安裝時自動產生——預設行為由 Caelestia 內建值決定。你只需要建立這個檔案、寫入你想覆寫的 section。未寫的 section 使用預設值。

shell.json 結構

shell.json 的 top-level section 對應桌面 shell 的各個元件和全域設定：

全域設定

元件設定

範例：常見客製化

 1{
 2    "bar": {
 3        "persistent": true,
 4        "workspaces": {
 5            "shown": 9
 6        },
 7        "clock": {
 8            "format": "%H:%M"
 9        }
10    },
11    "notifs": {
12        "expiration": 8000
13    },
14    "paths": {
15        "wallpapers": "~/Pictures/MyWallpapers"
16    },
17    "services": {
18        "gpu": "amd",
19        "time": {
20            "format24h": true
21        }
22    }
23}

Key 要對著實際版本驗：caelestia-shell 啟動時會改寫 shell.json、丟掉 schema 不認得的 key、只留有效子集（VM 實測 2.1.0：bar.clock.format、notifs.expiration、services.* 都被丟掉、只有 bar.persistent 與 workspaces.shown 留下）。寫覆寫檔後啟動 shell、再回頭看檔案剩什麼，就是這個版本的有效 schema——被丟掉的 key 代表該功能在這版不存在或搬了位置，去 token 或別的 section 找。schema 的權威來源是安裝進來的 /usr/lib/qt6/qml/Caelestia/Config/caelestia-config.qmltypes（config 編在 C++ plugin 裡、QML 原始碼查不到）。

一個經 2.1.0 驗證的實用例——idle 鎖屏時間（預設 3 分鐘鎖、10 分鐘關螢幕）延長到 2 小時：

 1{
 2    "general": {
 3        "idle": {
 4            "timeouts": [
 5                {
 6                    "timeout": 7200,
 7                    "idleAction": "lock"
 8                }
 9            ]
10        }
11    }
12}

Token 系統

shell-tokens.json 控制的是比 shell.json 更細粒度的視覺數值：

• 每個元件的 rounding（圓角半徑）
• 各區域的 spacing 和 padding
• 各類別文字的 font size
• 動畫的 duration 和 easing curve
• 元件的固定尺寸

官方的說法是：「Do NOT change any of these options if you do not know what you are doing.」這個警告的實際意義是——token 之間有隱含的依賴關係（某個 padding 值跟某個 rounding 值配合才好看），隨意改一個可能讓整體視覺走樣。而且 token 的名稱和結構可能在版本更新時變動，沒有向後相容承諾。

務實的做法是先不動 token，用 shell.json 做功能層面的客製化。等到你有明確的視覺需求（例如想把所有圓角改更大），再查 token 文件做精確調整。

自定義 Hyprland 設定

Caelestia 管理自己的 Hyprland 配置。你的自訂設定放在 hypr-user.lua（不是直接改 hyprland.lua）：

 1-- ~/.config/caelestia/hypr-user.lua
 2
 3-- 額外的 keybind
 4hl.bind("SUPER", "Return", "exec", "foot")
 5
 6-- monitor 配置
 7hl.config({
 8    monitor = {
 9        "DP-1, 2560x1440@144, 0x0, 1",
10        "HDMI-A-1, 1920x1080@60, 2560x0, 1",
11    },
12})
13
14-- 額外的 window rules
15hl.config({
16    windowrule = {
17        "workspace 8, class:^(firefox)$",
18    },
19})

Hyprland Lua 格式：Caelestia 已經遷移到 Lua 配置（對應 Hyprland v0.55+ 的格式變更）。如果你手上有舊的 hypr-user.conf，需要轉換成 Lua。轉換工具：hyprlang2lua（Go）或 hyprconf2lua（Python pip）。

配色與主題

Caelestia 的配色系統用 Material Design 3 的動態取色——從桌布圖片自動提取色彩，產生一套 primary / secondary / surface / error 色系，套用到所有元件。

1# 設定桌布並觸發動態取色
2caelestia wallpaper -f ~/Pictures/Wallpapers/mountain.jpg
3
4# 手動切換配色方案
5caelestia scheme set -n dynamic    # 動態（從桌布取）
6caelestia scheme set -n catppuccin # 如果有對應 template

自定義配色模板放在 ~/.config/caelestia/templates/，用 {{ primary.hex }}、{{ surface.hex }} 等變數。Caelestia 會在切換桌布時用新的色系填入這些變數，產生對應的配置檔。

Scheme 熱套用的啟動時序前提（兩台 VM 各實測一次、行為一致）：shell 對 ~/.local/state/caelestia/scheme.json 的 file watcher 只在啟動當下檔案已存在時建立。首次安裝、從未 scheme set 過的機器上，第一個 shell 實例啟動時 state 檔還不存在——之後下 scheme set 會寫入 state、CLI 回報也正確，但跑著的 UI 不變色。修法：scheme set 建好 state 檔後重啟一次 shell；那之後同一實例的配色切換都即時生效、不用再重啟。

重啟 shell 用 pkill -x qs：caelestia shell -k 可能靜默失敗（實測 CLI 1.1.1：指令回傳正常但 process 沒死、新起的實例偵測到舊實例就自行退出——看起來重啟了、實際同一個實例一直活著）。驗證重啟是否真的發生，比對 ps -o pid,lstart -p $(pgrep -x qs) 的 pid 與起始時間，別只看指令沒報錯。process 名是 qs（/usr/bin/qs 是 quickshell 的 symlink）、pgrep caelestia 找不到它。

不要改 AUR 安裝的檔案

AUR package（caelestia-shell）安裝的檔案在系統路徑下，更新時會被覆蓋。所有客製化都應該放在 ~/.config/caelestia/，Caelestia 會優先讀取使用者路徑的配置，沒有的才 fallback 到系統預設。

已知問題

Config 靜默破壞：Caelestia 的 token 名稱和配置結構可能在版本更新時變動，不會事先通知。更新後如果 shell 行為異常，先檢查 shell-tokens.json 裡的 key 是否還存在。

Notification backlog：Shell 可能因為積累大量通知而變卡。清除：

1caelestia shell notifs clear

quickshell-git 必須：穩定版的 quickshell 缺少 Caelestia 需要的 API。如果裝了穩定版，shell 會啟動失敗或功能不完整。確認用的是 quickshell-git：

1pacman -Q quickshell-git

工作區切換卡頓：在某些 GPU / 驅動組合下報告過隨機卡頓。排查方向：關閉 VRR（vrr = 0）、減少 blur passes、檢查 GPU 驅動版本。

Dotfile Repo 結構對應

Caelestia 的配置只追蹤覆寫用的檔案（shell.json、cli.json、hypr-user.lua），AUR package 安裝的原始檔案不進 repo：

 1~/dotfiles/
 2└── caelestia/
 3    └── .config/
 4        └── caelestia/
 5            ├── shell.json
 6            ├── shell-tokens.json   # 如果有自訂
 7            ├── cli.json
 8            ├── hypr-user.lua
 9            ├── hypr-vars.lua       # 如果有自訂
10            └── templates/          # 如果有自訂配色模板

monitor 專屬的覆寫（monitors/<name>/）是硬體相關的，跟 Hyprland 的 monitor 設定一樣，可能需要排除在 Git 外或用 template/local 機制處理。

Runtime 寫入會穿透 stow 的目錄 symlink 弄髒 repo：用 stow 部署時 ~/.config/caelestia 常是折疊的目錄 symlink、指向 repo 裡的 package 目錄，而 caelestia-shell 會在執行期往自己的 config 目錄寫（啟動時建 monitors/、改寫 shell.json）——這些寫入直接落進 dotfiles repo、git status 變髒（btop 往 themes/ 寫也是同一型）。配套：repo 的 .gitignore 把「app 會自己寫的路徑」列入（caelestia/.config/caelestia/monitors/ 等），shell.json 被改寫後 diff 一下、把有效 schema 的版本 commit 回去。

VM 測試 vs 實機測試

[VM 可測試] shell.json 配置語法、各 section 的效果（bar 模組顯示、launcher 搜尋行為、通知過期邏輯）、CLI 指令執行、hypr-user.lua 載入、配色方案切換指令。

[需實機測試] token 微調的視覺效果（間距和圓角的差異在軟體渲染下難以判讀）。動畫流暢度、blur 效能、動態取色品質、多螢幕佈局、日常穩定性等視覺與效能項目見 Caelestia 安裝的對應段落。

視窗管理與平鋪式工作流講了平鋪概念和選型，這裡直接進入 Hyprland 的配置實務。之後的 VM 實測專案會用這些配置做實際安裝和驗證。

macOS 讀者如果不打算在 Linux 或 VM 上跑 Hyprland，可以跳到同步、Bootstrap 與環境重建——bootstrap script 和 secret 管理的概念對 macOS 同樣適用。

章節文章

跨分類引用

• → 模組四：視窗管理與自動平鋪：平鋪式 WM 的概念和選型
• → 模組六：桌面 Rice 設計：compositor 之上的狀態列、啟動器、通知、配色系統
• → 模組七：桌面環境維護與故障排除：Hyprland crash、GPU hang、config 寫錯時的診斷和恢復
• → 模組八：同步、Bootstrap 與環境重建：跨機器搬移時硬體相關設定怎麼處理
• → Linux 工具選單：圖形桌面工具：在 Hyprland 下加圖形檔案管理員（Thunar / Nemo / PCManFM-Qt）的相依取捨

這裡的數據來自一次 VM 實測：先手動拼裝一套 waybar + wofi + mako + hyprlock，再換成 Caelestia，量兩者的安裝大小、記憶體、config 結構與失敗行為。

資源足跡：差約一個數量級

整合式 shell 把整個桌面畫在一個程式裡，這個程式通常是重量級的 UI runtime。Caelestia 建在 Quickshell（Qt6/QML）上，實測安裝足跡如下：

差距的來源是 Quickshell 這個 UI 框架——那 213 MB 是 quickshell 套件本身的安裝大小（一個建在 Qt6 上的 QML shell runtime），不是 Caelestia 的功能程式碼；而且 Qt6 的函式庫（qt6-declarative、qt6-base 等）還是它之上的額外相依，沒算進這 213 MB。手動拼裝的 waybar、wofi、mako 都是輕量的 wlroots/GTK 程式，加起來還不到 5 MB。

這一軸在資源受限的機器上才會咬人：舊筆電、記憶體小的 VPS、或你本來就想把桌面壓到最輕。在一台記憶體充裕的桌機上，400 MB 對 60 MB 的差別多半感覺不到；在一台 2 GB RAM 的機器上，這就是「桌面吃掉五分之一記憶體」跟「幾乎不佔」的差別。

失敗半徑：單點 vs 各自獨立

整合式 shell 把狀態列、通知、鎖屏、啟動器畫在同一個程式裡，所以這個程式崩潰時，這些東西會一起消失。手動拼裝的每個元件是獨立行程，一個崩掉不影響其他——mako（通知）崩了，waybar（狀態列）還在。

這不只是理論。這次 VM 實測就撞到一個具體案例：Caelestia 的鎖屏是由 Quickshell 主程式畫的，當這個持鎖的程式被中止時，Hyprland 依 ext-session-lock 協議保持鎖定並顯示「lockscreen app died」的死局——狀態列、通知、鎖屏因為同源，一個環節出事就連帶整個桌面 UI。手動拼裝的 hyprlock 是獨立的鎖屏程式，它崩潰同樣會觸發那個死局，但你的狀態列與通知不會跟著沒。

這一軸在穩定性敏感或無人值守的場景最關鍵。跑長時間無人盯著的任務時，「一個元件崩掉只損失那個元件」的隔離性，比「全部整合在一起」的一致性更值錢——因為沒人在旁邊立刻重啟。

配色一致性：最容易被低估的一軸

讓整個桌面配色一致，是整合式與手動拼裝差別最大、卻最常被忽略的地方。整合式 shell 因為所有元件在同一個程式裡，天生共用一套配色——Caelestia 的 dynamic scheme 從桌布抽一組 Material-3 palette，狀態列、通知、鎖屏、dashboard 全部同時套用，換張桌布整套 UI 跟著變。

手動拼裝要達到同樣的一致，得自己解決一個跨程式的問題：每個元件用不同的設定格式與主題引擎，它們之間不會自動共享顏色。這次手動拼裝那套時就撞到這點——waybar 的 GTK CSS 引擎讀不到 Hyprland 的 $ 顏色變數，結果 waybar 的 style.css 裡得手抄一份跟 Hyprland colors.conf 相同的 hex 色碼。換一次配色，就要在 waybar CSS、wofi CSS、mako config、hyprland colors 好幾個地方各改一遍。

解這個手工問題的標準做法，是加一層模板工具（matugen、pywal、wallust 之類）：從一張桌布或一套色票，自動生成每個元件的設定檔（例如 matugen/templates/rofi-colors.rasi 就是給 rofi 用的顏色模板）。這等於是手動重建 Caelestia 內建的那套 dynamic theming pipeline。所以配色一致這件事的真正取捨是：Caelestia 開箱就有「換桌布全套跟著變」，手動拼裝要嘛手抄 hex、要嘛自己搭一條 templating pipeline。

config 結構

配色一致的差別，也反映在 config 的形狀上。Caelestia 的使用者設定集中在一個 shell.json（實測約 24 行就涵蓋狀態列、通知、idle 行為）。手動拼裝的設定散在各元件目錄、各用各的格式：waybar 的 config.jsonc + style.css、wofi 的 config + style.css、mako 的 config、hypr 的數個 .conf。集中的好處是好懂好改；散開的好處是每個元件可以獨立替換（把 waybar 換成 ironbar 不影響其他），代價是你要管更多檔案、更多格式。

選型判準

沒有一種在所有軸上都贏。依你的情境對照：

重新評估的訊號（tripwire）

選了之後，出現這些訊號時值得回頭重新評估：

• 選了整合式，卻發現一直在跟它的設計決策對抗（想改的結構它不讓你改）——你要的其實是手動拼裝的自由度。
• 選了手動拼裝，卻發現配色維護（每次改色手抄多個檔案）吃掉大量時間——該加 templating 工具，或重新考慮整合式。
• 記憶體壓力浮現（整合式的 Qt runtime 在小機器上排擠其他程式）——往手動拼裝退。
• 整合式的一次更新靜默破壞了你的自訂設定（Caelestia README 明言 config 可能無預警變動）——評估這層快速移動的依賴值不值得。

下一步

• 整合式 shell 的概念定位、跟 AGS/Eww 的比較、三個 repo 的分工，見 Caelestia 總覽。
• 手動拼裝那幾個元件（狀態列、啟動器、通知）各自怎麼配置，見 桌面 Shell 元件。
• 配色系統本身（不管哪條路線）怎麼設計，見 配色系統、鎖屏與 GTK 主題。

這篇的足跡數字（安裝 230 MB vs 4.5 MB、RSS ~400 MB vs ~60 MB）與 lock-died 失敗案例，來自一次在 Apple Silicon UTM VM 上實際跑過兩種桌面棧的量測。

Hyprland 配置教了 compositor（Wayland 下負責視窗排列和畫面合成的程式）本身的設定。這個模組處理的是 compositor 之上的「桌面 shell」層——狀態列、啟動器、通知、鎖屏、桌布、配色系統。做法有兩條路：自己從 Waybar + Wofi + Mako 等獨立工具一個個拼裝，或用 Caelestia 這類預組裝的桌面 shell 一次部署。

章節文章

跨分類引用

• → 模組三：終端機與編輯器：Nerd Font 安裝是 Waybar icon 正常顯示的前提
• → 模組五：Hyprland 配置：compositor 的 appearance 設定（圓角、動畫）跟 rice 的視覺層互補
• → 模組一：管理工具與目錄結構：各 rice 元件的配置檔怎麼放進 stow 結構
• → Session Lock：鎖屏的安全模型——殺 process 不等於解鎖
• → 字型的可用集合在 process 啟動時決定：裝了字型但狀態列 / 通知還是豆腐時的判讀
• → fontconfig：字型搜尋、匹配與 fallback 機制

Linux 桌面環境跟 Windows 在故障模型上有根本的結構差異。Windows 的藍屏（BSOD）是核心層崩潰，整台機器停擺；Linux 桌面環境的大部分故障只影響 userspace，系統核心不受波及。理解這個隔離邊界，是判斷「當下該做什麼」的前提。

這個模組的閱讀方式跟其他模組不同。其他模組是線性學習——從頭讀到尾建立知識。這個模組是 reference——出問題時根據症狀查對應的恢復操作。第一篇建立概念模型，第二篇按場景查操作，第三篇教怎麼看日誌找根因。

章節文章

跨分類引用

• -> 模組五：Hyprland 配置：Hyprland 的配置結構和 hyprctl 指令
• -> 模組六：桌面 Rice 設計：waybar / wofi / mako 等工具的配置位置
• -> 模組八：同步、Bootstrap 與環境重建：環境損壞到無法修復時的重建策略

跟 X11 的分工對照能看清它的定位。X11 時代，X server 負責畫面、一個獨立的 window manager 負責視窗排列，兩者透過協定溝通；Wayland 取消這個分家，compositor 直接兼任兩者。所以在 Wayland 語境裡，「compositor」和「window manager」常指同一個東西——Hyprland 既是 compositor 也是 tiling window manager。

它跟桌面環境（desktop environment）是不同層次。桌面環境（GNOME、KDE）是一整套元件（面板、設定、通知、檔案管理），其中內含一個 compositor；而 Hyprland 這類「只有 compositor」的方案不含那圈桌面服務，面板、啟動器、鎖屏都要另外自己接。這條「整合度 vs 自己組裝」的軸線，是桌面環境選型的主題。

compositor 在故障排除中是一個關鍵的責任邊界，因為多個系統狀態由它持有、而非別的層：

• 它握著 DRM master：直接畫到顯示裝置的獨佔權由 compositor 持有，這是為什麼 compositor 必須從實體圖形 VT 起、不能從 SSH pty 起（SSH 連線裡沒有那個 seat 與 DRM 資源），也是為什麼它跟同樣要畫到 DRM 的 kmscon 之類 userspace console 會相衝。
• 它持有 session lock 狀態：Wayland 的 ext-session-lock 鎖是 compositor 層的狀態、跟 logind 獨立，殺掉鎖屏程式 compositor 仍保持鎖定——詳見 Session Lock。
• 它掛了、桌面才真的黑：反過來說，只要 kernel 還活著、compositor 以外的東西壞了，TTY 仍能登入操作。判斷「畫面黑」是 compositor 掛了、還是沒 getty、還是顯示輸出沒接，是桌面故障排除的第一個分岔。

相關概念：TTY（不依賴 compositor 的救生通道）、Session Lock（compositor 持有的鎖定狀態）、Rice（在 compositor 上做視覺客製）。

Wayland 下的 compositor（如 Hyprland、Sway）同時管理視窗排列與畫面輸出。鎖屏工具（Hyprlock、Swaylock）一旦啟動，桌面的「鎖定」狀態就由 compositor 透過 ext-session-lock-v1（Wayland 生態系的跨 compositor 鎖屏協議）持有。解鎖的正常動作是鎖屏 client 通過認證後呼叫 unlock_and_destroy（協議定義的 request），compositor 收到這個信號才釋放鎖定。

這個責任邊界在自動化測試、VM 演練、遠端操作時最容易出事，因為這些情境常用「殺 process」當「關掉一個東西」的通用手段。殺掉鎖屏 client 跳過了認證，compositor 不會釋放鎖——畫面會卡在失效保護狀態而非回到桌面。

logind 提示與 compositor 鎖的值可以不一致

鎖屏狀態牽涉兩個獨立的層，觸發方向和持有者不同：

loginctl lock-session 走 logind 層觸發鎖屏，鎖屏 client 收到信號後啟動、再向 compositor 取得 session lock。觸發方向是 logind → client → compositor；持有與強制執行方向是 compositor → 畫面。兩者方向相反，正好印證兩層是獨立的。

實測會遇到 LockedHint=no（logind 層說沒鎖）但畫面仍進不去——因為擋住畫面的是 compositor 的 ext-session-lock，跟 logind 提示是兩回事。判斷畫面進不進得去，看 compositor 層，不看 logind 層。

鎖屏 client 非正常結束時的失效保護

鎖屏 client 在持有鎖的狀態下死掉（被 kill、crash），compositor 沒有收到認證通過的信號，只能維持鎖定並顯示失效保護畫面。Hyprland 的失效保護畫面會直接給恢復指令：

1hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1'
2hyprctl --instance 0 'dispatch exec hyprlock'

allow_session_lock_restore 允許新的鎖屏 client 接管既有的鎖（否則新 client 會因「已經鎖了」被拒）。接管後是乾淨的鎖屏 prompt，用密碼正常解鎖。

備好 restore 路徑時，殺掉無回應的鎖屏 client 是合理操作——問題不在「殺」、在「以為殺完就回桌面」。restore 的前提是有另一個可操作的 session：另一個 TTY 或 SSH 連線。ext-session-lock 的安全語意允許 compositor 攔截 VT 切換快捷鍵（Ctrl+Alt+Fn），遇到 TTY 切不過去的情況，SSH 是替代救援通道（事先配好 SSH server，見常見故障場景與恢復操作的 GPU hang 段）。

判讀與操作

• 判讀鎖定狀態：loginctl show-session $(loginctl show-user $USER -p Display --value) -p LockedHint 查 logind 層；compositor 層看畫面能否操作。兩層不一致時以 compositor 層為準。
• 正常解鎖：通過鎖屏 client 的認證（密碼 / 指紋），client 呼叫 unlock_and_destroy，compositor 釋放鎖。
• 失效保護恢復：從另一個 TTY 或 SSH 執行 hyprctl --instance 0 'keyword misc:allow_session_lock_restore 1' + hyprctl --instance 0 'dispatch exec hyprlock'，重新拉起鎖屏 prompt 後認證解鎖。
• 自動化流程的代價：啟動鎖屏後，畫面會留在鎖定狀態直到有人通過認證。自動化測試若會觸發鎖屏，要把「需人工解鎖」算進代價。
• 診斷路由：「畫面卡住 / 螢幕鎖了沒」當成一般 Linux 狀態判讀問題（跟判程式活著、判服務歸屬同類）時，見程序、服務與狀態怎麼判——它把「判 session 有沒有被鎖」放進「讀權威狀態、別看畫面猜」的通用診斷紀律裡。
• 延伸閱讀：鎖屏的視覺配置（背景、輸入框、時鐘 label）見配色系統、鎖屏與 GTK 主題的 Hyprlock 段；桌面故障恢復流程見常見故障場景與恢復操作。持鎖的那個 compositor 到底是什麼、還握著哪些系統狀態，見 Compositor 術語卡。

邊界條件

正常認證解鎖（走 unlock_and_destroy）後鎖屏 client 結束，compositor 已回到非鎖定狀態，不觸發失效保護。失效保護只在「持鎖中非正常結束」時出現。

Sway/swaylock 在 client 死掉時沒有畫面上的恢復提示（不像 Hyprland 會印指令），得預先知道走 TTY 或 SSH 執行 restore。「鎖是 compositor 持有、解鎖要認證」是 ext-session-lock 協議層的共通約束；失效保護的具體呈現方式因 compositor 而異。