Caelestia 的安裝有兩條路：用 CLI 工具一鍵部署完整 dotfiles，或只安裝 shell 元件保留自己的 Hyprland 配置。兩者的前提都是 Hyprland 已經安裝且能正常啟動。

前提條件

  • 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穩定版 shell（UI 元件）
caelestia-shell-git開發版 shell（最新功能，可能不穩定）
caelestia-cliCLI 工具（安裝、主題切換、截圖、錄影等）

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-gitQuickshell 框架（穩定版不夠用）
ddcutil外接螢幕亮度控制
brightnessctl筆電螢幕亮度
libcava音訊視覺化
networkmanager網路管理
lm-sensors硬體溫度感測
fishFish shell（部分功能依賴）
aubio音訊分析
libpipewirePipeWire 音訊整合
qt6-declarativeQML runtime
material-symbols (font)Material Design icon 字型
caskaydia-cove-nerdNerd Font

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

CLI 依賴

套件用途
libnotify通知發送
swappy截圖標註
grimWayland 截圖
dart-sassSCSS 編譯
wl-clipboard剪貼簿
slurp區域選取
gpu-screen-recorder螢幕錄影
glib2GLib 工具
cliphist剪貼簿歷史
fuzzel模糊搜尋選單

登入管理器

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 常用指令

指令功能
caelestia shell -d啟動 shell（背景）
caelestia shell -s列出所有 IPC 指令
caelestia install完整安裝 dotfiles
caelestia update系統 + dotfiles 更新
caelestia scheme set -n dynamic設定動態配色方案
caelestia wallpaper -f <path>設定桌布
caelestia screenshot截圖
caelestia record螢幕錄影
caelestia clipboard剪貼簿歷史
caelestia emojiEmoji / glyph 選取器
caelestia toggle切換特殊工作區
caelestia resizer視窗 resize daemon

首次啟動常見問題

黑屏：通常是缺少 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 能讀」，不適合評估視覺效果和日常使用體驗。