Hyprland 核心配置

2026-06-29

Hyprland v0.55+ 使用 Lua 作為配置語言。Lua 語法基礎見 Lua 腳本語言。

配置檔位置與格式

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 函式，處理不同互動模式：

函式	行為	適用場景
`hl.bind()`	按一次觸發	多數快捷鍵
`hl.binde()`	長按連續觸發	調整視窗大小、音量
`hl.bindm()`	滑鼠綁定	拖曳移動 / 調整視窗
`hl.bindr()`	放開時觸發	切換模式
`hl.bindl()`	輸入鎖定也觸發	合蓋開關、鎖屏時的媒體鍵
`hl.bindel()`	連續 + 鎖定	鎖屏時的音量鍵（長按連續、鎖定可用）

[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 環境設定與測試矩陣。

#dotfile #hyprland #wayland #linux