本篇的配置範例使用 Lua 語法（Hyprland v0.55+）。Lua 基礎見 Lua 腳本語言。

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功能
hyprexpoworkspace 鳥瞰（所有 workspace 縮圖一覽）
hy3i3/sway 風格的手動 tiling layout（替代 dwindle）
hyprspace類似 macOS Mission Control 的 workspace 切換動畫
hyprbars視窗標題列（可自訂按鈕）
hyprtrails游標拖尾特效

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 與實機測試對照

項目VM 可測試需實機測試
配置語法 / 結構可
Keybind 設計可
Window rules 邏輯可
Workspace 切換可
Layout 參數可
Autostart 順序可
Plugin 配置部分視覺類
動畫流暢度必要
Blur 效能 / 品質必要
多螢幕排列必要
HiDPI 縮放必要
觸控板 / 手勢必要
媒體鍵 / 亮度鍵必要
NVIDIA 驅動設定必要
螢幕分享必要
休眠 / 喚醒必要
合蓋行為必要