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。

前提條件

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

配置檔路徑

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 安裝的對應段落。

這裡的數據來自一次 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 上實際跑過兩種桌面棧的量測。