Hyprland 安裝與環境建置

Mon, 29 Jun 2026 00:00:00 +0000

Hyprland 的安裝分三層：compositor（負責視窗管理與畫面合成的核心程式，詳見 Wayland 顯示協議）本身、GPU 驅動、桌面配套工具。Compositor 只管視窗排列和畫面輸出，其餘功能（status bar、launcher、通知、音訊、藍牙、網路）都需要另外裝。本篇以 Arch Linux 為主要說明對象，其他發行版在最後簡述。

核心套件

1sudo pacman -S hyprland xorg-xwayland xdg-desktop-portal-hyprland

套件	角色
`hyprland`	Compositor 本體，在 Arch 官方 `extra` repo，不需要 AUR
`xorg-xwayland`	X11 相容層，讓舊 X11 應用程式在 Wayland 環境裡正常運行
`xdg-desktop-portal-hyprland`	Hyprland 專屬的 portal backend，處理 screen sharing 和檔案對話框

[VM 可測試] 套件安裝本身在 VM 和實機上完全相同。

GPU 驅動

GPU 驅動決定 Hyprland 的渲染是走硬體加速還是軟體 fallback。AMD 和 Intel 開箱即用，NVIDIA 需要額外配置。

AMD（推薦，開箱即用）

1sudo pacman -S mesa vulkan-radeon libva-mesa-driver mesa-vdpau

mkinitcpio MODULES 加入：amdgpu

環境變數（放在 Hyprland 配置裡）：

1env = {
2    "LIBVA_DRIVER_NAME, radeonsi",
3    "VDPAU_DRIVER, radeonsi",
4    "AMD_VULKAN_ICD, RADV",
5}

AMD 是 Hyprland / Wayland 生態支援最好的 GPU。如果是新購硬體、有選擇的餘地，AMD 是最省事的選項。

Intel（開箱即用）

1sudo pacman -S mesa vulkan-intel intel-media-driver

mkinitcpio MODULES 加入：i915

1env = {
2    "LIBVA_DRIVER_NAME, iHD",
3    "VDPAU_DRIVER, va_gl",
4}

Intel 內顯在 Wayland 上表現穩定，適合筆電和輕度桌面使用。

NVIDIA（需要額外配置，非官方支援）

[需實機測試] NVIDIA 的所有設定在 VM 中無意義——VM 使用 virtio-gpu 或軟體渲染，不走 NVIDIA 驅動。以下步驟只在實體機有 NVIDIA 顯卡時才需要。

Hyprland 官方不支援 NVIDIA，但社群有成熟的 workaround。最低版本需求：

NVIDIA driver >= 555（555 引入完整 GBM 支援和 explicit sync，是 Wayland 硬體渲染的最低依賴。535 系列有 explicit sync 問題，Wayland 下容易 flicker。590+ 修復多數 HDR 和多螢幕邊界問題）
xorg-xwayland >= 24.1
wayland-protocols >= 1.34

安裝：

1sudo pacman -S nvidia-dkms nvidia-utils libva-nvidia-driver
2# 32-bit 支援（遊戲可能需要）：
3sudo pacman -S lib32-nvidia-utils

mkinitcpio MODULES（依硬體配置選擇）：

純 NVIDIA 桌機：

1MODULES=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)

Intel + NVIDIA hybrid 筆電（Intel 排在 NVIDIA 前面）：

1MODULES=(i915 nvidia nvidia_modeset nvidia_uvm nvidia_drm)

更新 initramfs：

1sudo mkinitcpio -P

Modprobe 設定：

1# /etc/modprobe.d/nvidia.conf
2options nvidia_drm modeset=1

GRUB kernel parameter：

1# /etc/default/grub
2GRUB_CMDLINE_LINUX_DEFAULT="... nvidia_drm.modeset=1 nvidia_drm.fbdev=1"

更新 GRUB：

1sudo grub-mkconfig -o /boot/grub/grub.cfg

Hyprland 配置裡的 NVIDIA 環境變數：

1env = {
2    "LIBVA_DRIVER_NAME, nvidia",
3    "__GLX_VENDOR_LIBRARY_NAME, nvidia",
4    "GBM_BACKEND, nvidia-drm",         -- 如果 Firefox crash，移除這行
5    "NVD_BACKEND, direct",
6}

Cursor 修正（NVIDIA 常見的硬體 cursor 問題）：

1hl.config({
2    cursor = {
3        no_hardware_cursors = true,
4        allow_dumb_copy = true,
5    },
6})

Suspend/resume 支援：

1sudo systemctl enable nvidia-suspend.service nvidia-hibernate.service nvidia-resume.service

檢查 GPU 驅動狀態

1lspci -k | grep -A 3 VGA        # 查看使用中的驅動
2glxinfo | grep "OpenGL renderer" # 查看活躍的 renderer
3vulkaninfo --summary             # Vulkan 裝置資訊

GPU 驅動相關的故障診斷（driver hang、畫面凍結、suspend/resume 後異常）見桌面環境維護與故障排除。

桌面配套套件

Hyprland 只管視窗，以下是一個可用桌面需要的配套工具：

 1sudo pacman -S \
 2  kitty waybar wofi mako \
 3  polkit-gnome grim slurp wl-clipboard cliphist \
 4  hyprpaper hyprlock hypridle \
 5  pipewire pipewire-alsa pipewire-jack pipewire-pulse wireplumber \
 6  pamixer pavucontrol brightnessctl \
 7  bluez bluez-utils blueman \
 8  networkmanager network-manager-applet \
 9  thunar gvfs \
10  qt5-wayland qt6-wayland \
11  ttf-meslo-nerd noto-fonts noto-fonts-cjk

類別	套件	用途
終端機	`kitty`	Hyprland 預設配置使用的 terminal emulator
狀態列	`waybar`	JSON config + CSS styling 的 status bar
啟動器	`wofi`	Wayland 原生 app launcher
通知	`mako`	輕量 notification daemon
認證代理	`polkit-gnome`	GUI 權限提升（sudo 對話框）
截圖	`grim` + `slurp`	截圖工具 + 選區工具
剪貼簿	`wl-clipboard` + `cliphist`	剪貼簿存取 + 歷史記錄
桌布	`hyprpaper`	靜態桌布
鎖屏	`hyprlock`	Hyprland 配套鎖屏
Idle	`hypridle`	閒置偵測（觸發鎖屏/休眠）
音訊	`pipewire` + `wireplumber` + `pipewire-pulse`	音訊 server（取代 PulseAudio）
音量控制	`pamixer`（CLI）+ `pavucontrol`（GUI）	音量調整
亮度	`brightnessctl`	螢幕亮度（筆電）
藍牙	`bluez` + `bluez-utils` + `blueman`	藍牙協定 + GUI 管理
網路	`networkmanager` + `nm-applet`	網路管理 + system tray 圖示
檔案管理	`thunar` + `gvfs`	圖形檔案管理器 + 回收筒/遠端掛載
Qt 相容	`qt5-wayland` + `qt6-wayland`	Qt 應用在 Wayland 下正常運行
字型	`ttf-meslo-nerd` + `noto-fonts-cjk`	Nerd Font（waybar icon 需要）+ CJK 字型

AUR 補充套件（用 yay 或 paru）：

1yay -S grimblast-git   # Hyprland 截圖 wrapper
2yay -S swww            # 動態桌布（hyprpaper 的替代）
3yay -S rofi-wayland    # 功能比 wofi 更豐富的 launcher

[已驗證] 套件安裝在 VM 中完全可執行。waybar、wofi、mako、hyprlock 在 virtio-gpu-gl-pci 加速下正常 render（Hyprland 0.55 + UTM 4.7.5 實測）。

[需實機測試] 藍牙（bluez）、亮度（brightnessctl）、音訊裝置偵測（pipewire）需要實際硬體。

登入管理器

Hyprland 預設不含登入管理器。三個選項：

從 TTY 直接啟動（最簡單）

登入文字介面後直接執行 Hyprland。建議用 wrapper script 設定必要的環境變數：

1#!/bin/sh
2# ~/start-hyprland.sh
3export XDG_SESSION_TYPE=wayland
4export XDG_CURRENT_DESKTOP=Hyprland
5export XDG_SESSION_DESKTOP=Hyprland
6exec Hyprland

1chmod +x ~/start-hyprland.sh
2~/start-hyprland.sh

greetd + tuigreet（推薦）

greetd 是一個輕量的登入管理器，tuigreet 是它的 TUI 前端：

1sudo pacman -S greetd greetd-tuigreet

設定 /etc/greetd/config.toml：

1[terminal]
2vt = 1
3
4[default_session]
5command = "tuigreet --cmd Hyprland"
6user = "greeter"

自動登入（可選）：

1[initial_session]
2command = "Hyprland"
3user = "yourusername"

啟用服務：

1sudo systemctl enable greetd

SDDM

如果已經有 KDE 或偏好圖形化登入介面：

1sudo pacman -S sddm
2sudo systemctl enable sddm

SDDM 會自動偵測到 Hyprland 並在登入畫面顯示它作為 session 選項。

[VM 可測試] 登入管理器的設定在 VM 中可完整測試。

首次啟動常見問題

症狀	原因	修正
黑屏、沒有 cursor	缺少 polkit agent 或 seatd service	`sudo systemctl enable --now seatd` 或安裝 `polkit-gnome`
開不了 terminal	預設 keybind 用的是 kitty，但 kitty 沒裝	`sudo pacman -S kitty` 或改 keybind 指向已安裝的 terminal
Cursor 不見（NVIDIA）	硬體 cursor 問題	設定 `cursor { no_hardware_cursors = true }`
Portal 衝突，screen share 失敗	同時裝了多個 portal backend	移除 `xdg-desktop-portal-gnome` 和 `xdg-desktop-portal-gtk`
沒有音訊	PipeWire 服務未啟動	`systemctl --user enable --now pipewire wireplumber`
Config 報錯但不影響使用	自動產生的預設 config 語法不完整	emergency keybind 仍可用：SUPER+Q 開 terminal、SUPER+M 離開

配置格式：Lua 取代 hyprlang（v0.55+）

Hyprland v0.55（2026 年 4 月）起，配置格式從 hyprlang（.conf）遷移到 Lua（.lua）。舊的 hyprland.conf 在沒有 .lua 檔案時仍然可用，但 hyprlang 已被標記為 deprecated，預計在後續版本移除。

格式	檔案	狀態
Lua（新）	`~/.config/hypr/hyprland.lua`	推薦
hyprlang（舊）	`~/.config/hypr/hyprland.conf`	deprecated

遷移工具：hyprlang2lua（Go，有瀏覽器版）、hyprconf2lua（Python pip）、hypr-migrate。

本系列後續文章（Hyprland 核心配置、Workspace 與外觀、Caelestia）都使用 Lua 格式。如果在網路上看到 .conf 格式的教學，多數仍然可用，但建議儘早遷移到 Lua。

拆分配置用 Lua 原生的 require()：

1-- hyprland.lua
2require("keybinds")    -- 載入同目錄下的 keybinds.lua
3require("rules")       -- 載入同目錄下的 rules.lua
4require("appearance")

詳細的配置語法和設定邏輯在核心配置和 Workspace、Window Rules 與外觀。

其他發行版

Fedora

Fedora 39 起即在官方 repo。安裝：

1sudo dnf install hyprland

JaKooLit 提供自動化安裝腳本（github.com/JaKooLit/Fedora-Hyprland），Fedora 42+ 運作良好。

NixOS

NixOS 有官方 module，在 configuration.nix 加入：

1programs.hyprland.enable = true;

Home Manager 也有對應 module，可以宣告式管理 Hyprland 配置。

Ubuntu

不推薦。Ubuntu 的 point-release 模型跟 Hyprland 的 bleeding-edge 更新節奏衝突。沒有官方 PPA，從 source 編譯可行但維護成本高。如果一定要用 Debian 系，Arch 的 rolling release 或 Fedora 的半年週期更適合 Hyprland。

安裝後的下一步

安裝完成後，VM 環境的額外設定（環境變數、效能調整、測試矩陣）見 VM 環境設定與測試矩陣。配置檔的組織方式和 keybind 設計見 Hyprland 核心配置。

Installation on Tarragon