前提條件

• 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 能讀」，不適合評估視覺效果和日常使用體驗。