2026 Hyprland学习笔记

Hyprland 名气很大，很久之前我就知道。并试用过。当时只是因为我的IDEA2021在这个桌面环境中显示的有点问题，后来就放弃使用了Hyprland。现在我的IDEA已经升级成2026了，与是打算重新用起来。

目前我主用的桌面环境是Awesome WM 从2023-01开始用到现在。在此之前用的是i3wm。因为当时i3wm在使用浏览器播放视频总是出现花屏的情况。才切的awesome。以上是我的过去的习惯。

本文是我探索的过程记录，并非以教程为视角。仅供参考。

Hyprland简介

Hyprland 是一个现代化的 Wayland 动态平铺窗口管理器（Compositor），主要特点是：

• 自动平铺：窗口会自动排列，适合键盘高效操作。
• 动画漂亮：切换窗口、工作区时动画流畅，比传统平铺 WM 更现代。
• 高度可定制：快捷键、窗口规则、动画、布局都能自己配置。
• 基于 Wayland：不是 X11，适合较新的 Linux 桌面环境。
• Arch Linux 用户很多：社区活跃，教程和配置案例丰富。
• 不是完整桌面环境：通常还要搭配 Waybar、wofi/rofi、通知程序、锁屏等组件。

可以简单理解为：Hyprland ≈ Wayland 时代更漂亮、更现代的 i3/Awesome 风格平铺桌面。

https://github.com/hyprwm/Hyprland

目标与原则

1. 刚切为主力桌面环境的话，百分百会遇到各种问题。为了防止自己中途放弃，我决定这次至少使用一周时间。超过一周，无法坚持下去的话，就在放弃。强迫自己与时俱进。
2. 尽量不修改默认配置，如按键配置。尽量用Hyprland的默认值。 为什么这样做呢？因为以前我无论用什么软件都喜欢把默认配置修改成自己以前熟悉的手感去使用。好处是上手快，缺点就是要花很多时间去修改配置。存在改来改过，左也不是右也不是的情况，最终反而浪费了很多时间。 因为常常会出现迁一发动全身的情况 。

入门

开机Warning

学习从这个Warning开始吧。

Warning: You're using an autogenerated config! Edit the config file to get rid of this message. (configfile: /home/itkey/.config/hypr/hyprland.lua)
SUPER+Q-> kitty (if it doesn't launch, make sure it's installed or choose a different terminal in the config)
SUPER+M-> exit Hypriand

从这个警告信息，能得知以下信息：

• 配置文件~/.config/hypr/hyprland.lua
• 默认SUPER+Q 打开kitty 终端
• 默认SUPER+M 退出桌面
  有这些信息基本就可以使用这个桌面了。

Getting started

首次使用，开机会有个向导程序。可以点Next看下一步的内容：

首先，我们需要安装一些系统正常运行所必需的软件包。我的电脑信息如下：

组件	状态	当前软件
Authentication agent*	❌ Missing	-
Terminal*	✅ Installed	kitty
Wallpaper	✅ Installed	hyprpaper
Notification Daemon*	❌ Missing	-
Application launcher	✅ Installed	wofi
File manager*	✅ Installed	ranger
Pipewire*	✅ Running	pipewire
XDG Desktop Portal*	❌ Missing	-
Status bar / shell	✅ Installed	waybar
Clipboard*	✅ Installed	wl-copy

这里的*号是必须的。然后鼠标放到每个项目上会有一个建议。

与是我就来按照建议安装一下：

# Authentication agent*
sudo pacman -S hyprpolkitagent
# XDG Desktop Portal*
sudo pacman -S xdg-desktop-portal-hyprland
# Notification Daemon*
sudo pacman -S dunst

然后我安装完成后，重新进入桌面在看一下。

这时我发现Authentication agent*与XDG Desktop Portal* 还是显示Missing。

正在我写文章的时候XDG Desktop Portal* 由Missing变成了Running:xdg-desktop-portal-hyprland，

这里我在想会不会是因为服务没有启动才会这样显示的呢？

实测当我执行

systemctl --user start hyprpolkitagent

那个检测界面，会显示Authentication agent*:Running:hypropolkitagent 。看来不用重启也能看到效果。

这个服务如何设置开机启动呢？编辑

~/.config/hypr/hyprland.lua

增加以下内容：

-- 开机启动
hl.on("hyprland.start", function()
	hl.exec_cmd("systemctl --user start hyprpolkitagent")
end)

重启后，在测试这次发现全都正常了，没有在显示Missing 了。

默认应用设置

这里默认的File Manager是dolphin,默认的Launcher是hyprlauncher。

为了品尝原味的，我也来安装一下吧。

# File Manager
sudo pacman -S dolphin
# Launcher
sudo pacman -S hyprlauncher

开机启动设置

我把我在awesome 之中开机脚本迁移到这里

~/.config/hypr/hyprland.lua

增加以下内容：

-- 开机启动
hl.on("hyprland.start", function()
	hl.exec_cmd("systemctl --user start hyprpolkitagent")
	-- 输入法
	hl.exec_cmd("fcitx5")
	-- 自动挂载U盘
	hl.exec_cmd("udiskie")
	-- 改键
	hl.exec_cmd("xmodmap /home/itkey/.xmodmap")
	-- 连接wifi的图形化管理工具
	hl.exec_cmd("MAX_RETRIES=3 SLEEP_SECONDS=5 /home/itkey/.soft/bin/connect-SAMKING_NJ-wifi.sh")
	-- 音量调节托盘
	hl.exec_cmd("volumeicon")
end)

默认快捷键

• SUPER + Q = Terminal 终端
• SUPER + E = File Manger 文件管理
• SUPER + R = Launcher 程序启动器
• SUPER + C = Close window 关闭窗口
• SUPER + V = Toggle floating 切换浮动
• SUPER + M = Exit Hyprland 注销
• SUPER + 1- 9 = Workspaces 1- 9 切换工作空间
• SUPER + SHIFT + 1-9 = Move window to workspace 1 - 9
• SUPER + Arrows = Move focus around 切换不同窗口

至此完成了入门的配置了吧。

这次重启后，就只有一个壁纸了，没有任何界面了。

如果还想看到向导，可以命令行中执行

hyprland-welcome 

---

waybar状态栏呢

默认情况下，是无法看到状态栏的。那么我如何看以下信息呢？

1. 当前在哪个Workspace
2. 当前任务栏中有哪些正在运行的程序？比较我以前用来切换wifi的程序，微信之类的。

我了解了一下，可以通过 Waybar来实现这样的功能。

https://github.com/Alexays/Waybar

开机启动项目中增加

	hl.exec_cmd("waybar")

配置文件：

~/.config/waybar/config.jsonc

内容，我是从https://github.com/Alexays/Waybar/blob/master/resources/config.jsonc之中复制过来的。

我的修改如下：

1. 首先我觉得默认的高度太高了，我注释了这一行，实现自动高度

    //"height": 30, // Waybar height (to be removed for auto height)

2. 默认的我工作区是无法正常显示的，我看了配置文件。发现默认的配置文件是在sway中使用的，所以调整了以下部分。

    "modules-left": [
        "ext/workspaces",
        "hyprland/submap",
        "custom/media"
    ],
    // 使用 Wayland 工作区协议，兼容 Hyprland 的 Lua 配置接口。
    "ext/workspaces": {
        "format": "{name}",
        "on-click": "activate",
        "all-outputs": false
    },

其中ext/workspaces 为了解决，鼠标点击工作区没有反应的问题。

3. 右侧的电源按钮，点击会闪退，AI教我这么做，可以修复 。

nvim ~/.config/waybar/power_menu.xml

内容如下：

<?xml version="1.0" encoding="UTF-8"?>

<interface>
    <object class="GtkMenu" id="menu">
        <child>
            <object class="GtkMenuItem" id="suspend">
                <property name="label">Suspend</property>
            </object>
        </child>

        <child>
            <object class="GtkMenuItem" id="hibernate">
                <property name="label">Hibernate</property>
            </object>
        </child>

        <child>
            <object class="GtkMenuItem" id="shutdown">
                <property name="label">Shutdown</property>
            </object>
        </child>

        <child>
            <object class="GtkSeparatorMenuItem" id="delimiter1"/>
        </child>

        <child>
            <object class="GtkMenuItem" id="reboot">
                <property name="label">Reboot</property>
            </object>
        </child>
    </object>
</interface>

目前为止基本够我使用了，这个默认设置，看起来一块块色块，对我看来挺花哨的。我更喜欢简洁实现的风格的。

样式自定义

默认的样式对我来说，大彩块太多了。而且信息密度不大。我用AI帮我优化了一下，最终效果如下：

增加样式表

/home/itkey/.config/waybar/style.css

内容如下：

/* 保留默认字体和栏背景，统一模块文字颜色。 */
* {
    font-family: FontAwesome, Roboto, Helvetica, Arial, sans-serif;
    font-size: 13px;
    color: #ffffff;
}

window#waybar {
    background-color: rgba(43, 48, 59, 0.5);
    border-bottom: 3px solid rgba(100, 114, 125, 0.5);
}

window#waybar.hidden {
    opacity: 0.2;
}

button {
    box-shadow: inset 0 -3px transparent;
    border: none;
    border-radius: 0;
}

#workspaces button {
    padding: 0 5px;
    background-color: transparent;
}

#workspaces button:hover {
    background: rgba(0, 0, 0, 0.2);
    box-shadow: inset 0 -3px #ffffff;
}

#workspaces button.focused,
#workspaces button.active {
    background-color: #64727d;
    box-shadow: inset 0 -3px #ffffff;
}

#workspaces button.urgent {
    background-color: #eb4d4b;
}

#window,
#workspaces {
    margin: 0 4px;
}

.modules-left > widget:first-child > #workspaces {
    margin-left: 0;
}

#clock,
#battery,
#cpu,
#memory,
#disk,
#temperature,
#backlight,
#network,
#pulseaudio,
#wireplumber,
#custom-media,
#tray,
#mode,
#idle_inhibitor,
#scratchpad,
#power-profiles-daemon,
#mpd {
    padding: 0 10px;
}

#custom-media {
    min-width: 100px;
}

#language {
    padding: 0 5px;
    margin: 0 5px;
    min-width: 16px;
}

#keyboard-state {
    margin: 0 5px;
    min-width: 16px;
}

#keyboard-state > label {
    padding: 0 5px;
}

/* 右侧模块左右各留 5px，避免默认内边距叠加成大空隙。 */
window#waybar .modules-right > widget > .module {
    padding: 0 5px;
    margin: 0;
}

/* 所有右侧模块及其状态都透出栏背景，取消色块和变色动画。 */
.modules-right,
.modules-right * {
    background-color: transparent;
    background-image: none;
    color: #ffffff;
    box-shadow: none;
    animation: none;
}

加载最新的配置

 pkill -USR2 -x waybar

解决gdm无法默认启动Hyprland的问题

archlinux 我使用gdm的。通常情况下，会记住最后一次启动的桌面环境的，比如：我用 Hyprland ，下次开机应该会自动选择这项目的，但是实际上下次会变成GNOME，请问有办法解决这样的问题吗？

AI给我的解决办法：

sudo nvim /var/lib/AccountsService/users/itkey

修改之前的值如下：

[User]
Session=hyprland
SessionType=x11
Icon=/home/itkey/.face
SystemAccount=false

这里的SessionType=x11明显是错误的，把它修改成SessionType=wayland

重启电脑解决问题。

按键绑定

窗口全屏

窗口全屏是我常用的，在默认的配置中并没有，于是我加了一下。

-- 窗口全屏
hl.bind(mainMod .. " + F", hl.dsp.window.fullscreen())

这里有个体验不错的，修改配置文件后立即生效，不用像awesome 要重新加载配置。

浏览器

-- Microsoft Edge
hl.bind(mainMod .. " + B", hl.dsp.exec_cmd("/opt/microsoft/msedge/microsoft-edge"))

IDEA 2026显示不清楚

我使用的IntelliJ IDEA 2026.2.0.1版本，在Hyprland 显示比较模糊，看起来有颗粒感，就像小图片强行放大显示的那种感觉，有没有什么优化办法呢？

这个问题就是当前让我放弃使用Hyprland的问题，因为我当前用的是IDEA2021好像没有原生支持Wayland，没解决成功，现在用的是新版本，又有AI。这次应该能解决了。

测试

hyprctl monitors

重点看scale: 1.50

说明屏幕是有缩放的。

执行

hyprctl clients

找到 IntelliJ IDEA，看看：

xwayland: 1

解决办法：

最推荐：让 IDEA 原生跑 Wayland

IDEA 中打开：

Help
→ Edit Custom VM Options

增加一行（如果已经存在则修改）

-Dawt.toolkit.name=WLToolkit

这下就非常清晰了。

屏幕DPI设置

我的显示器一个是笔记本内置显示屏，别一个是外接4K显示器。

-- 笔记本内置显示屏
hl.monitor({
	output = "eDP-1",
	mode = "preferred",
	position = "auto",
	scale = 1.5,
})

-- 外接显示器
hl.monitor({
	output = "HDMI-A-1",
	mode = "preferred",
	position = "auto",
	scale = 2,
})

微信显示模糊

类似上面的IDEA，微信默认显示也很模糊，经检查微信 xwayland: 1

也就是说微信现在是 X11 → XWayland → Hyprland。如果你的 4K 显示器还是 scale = 1.5（或你后来改成了 1.75），Hyprland 会再对这个 XWayland 窗口缩放，所以就容易出现你说的"低分辨率图片被放大"的感觉。Hyprland 官方也明确说明 XWayland 在 HiDPI 缩放下会出现 pixelated / blurry。

解决思路：

1. 让Hyprland 不自动缩放微信 。
2. 让微信自己进行缩放

让Hyprland 不自动缩放微信

~/.config/hypr/hyprland.lua

hl.config({
    xwayland = {
        force_zero_scaling = true,
    },
})

这时就会发现微信不模糊了，但是显示的很小。其实这一步我觉得很好了，微信小一些别人还看不清楚我在聊什么呢。

让微信自身缩放

命令行直接启动

QT_SCALE_FACTOR=1.5 wechat

就可以实现自身缩放1.5了，而且这次不在模糊了。

直接修改启动图标

nvim /usr/share/applications/wechat.desktop

#Exec=/opt/wechat/wechat %U
Exec=QT_SCALE_FACTOR=1.5  /opt/wechat/wechat %U

这样启动微信就默认缩放啦。

lua lsp优化

我用LazyVim 编辑/home/itkey/.config/hypr/hyprland.lua 文件，一直会显示● Undefined global hl. 有没有什么优化办法？

可以优化，而且这是 Lua LSP（lua-language-server）不知道 hl 是 Hyprland 注入的全局变量，并不是你的配置有错。

Hyprland 官方专门提供了 Lua stubs，推荐让 LSP 加载它。(Hypr Land 维基1)

推荐做法

在 Hyprland 配置目录创建：

nvim ~/.config/hypr/.luarc.json

写入：

{
  "workspace": {
    "library": [
      "/usr/share/hypr/stubs"
    ]
  },
  "diagnostics": {
    "globals": [
      "hl"
    ]
  }
}

然后重新打开：

nvim ~/.config/hypr/hyprland.lua

这样通常会同时解决两个问题：

1. Undefined global 'hl' 消失
2. LazyVim/Lua LSP 能知道 hl 的 API，获得更好的 自动补全、参数提示和类型提示

Hyprland 官方就是这样建议配置 Lua LSP 的。(Hypr Land 维基1)

配置文件拆分

根据官方文档把配置文件拆成了多个小文件，方便分类管理。

-- Hyprland 配置入口：按顺序加载各模块。
-- 官方文档：https://wiki.hypr.land/Configuring/Start/#using-multiple-configuration-files
-- 常用程序在 config/programs.lua 中设置，由快捷键模块引用。

require("config.monitors")    -- 显示器与缩放
require("config.autostart")   -- 开机启动
require("config.environment") -- 环境变量
require("config.permissions") -- 权限设置示例
require("config.appearance")  -- 窗口外观与 XWayland 缩放
require("config.animations")  -- 动画与曲线
require("config.layouts")     -- 平铺布局
require("config.misc")        -- 壁纸与杂项
require("config.input")       -- 键盘、鼠标、触控板与手势
require("config.keybinds")    -- 快捷键
require("config.rules")       -- 窗口、工作区与图层规则

├── config
│   ├── animations.lua
│   ├── appearance.lua
│   ├── autostart.lua
│   ├── environment.lua
│   ├── input.lua
│   ├── keybinds.lua
│   ├── layouts.lua
│   ├── misc.lua
│   ├── monitors.lua
│   ├── permissions.lua
│   ├── programs.lua
│   └── rules.lua
└── hyprland.lua

这些是我让AI帮我拆分的。我的提示词如下：

请帮我把配置文件，按官方文档的方法拆分一下。

Using Multiple Configuration Files
Splitting hyprland's configuration across multiple files is an easier way of managing the configuration. To source or reference other files we use lua's require function.

You can refer to the files using relative paths from the location of . Example:hyprland.lua

-- refers to $XDG_CONFIG_HOME/hypr/awesomeconf/keybinds.lua
require("awesomeconf/keybinds")

-- refers to $XDG_CONFIG_HOME/hypr/awesomeconf/animation.lua
require("awesomeconf.animation")

You can use either or as a directory separator. The separator is UNIX specific whilst the separator is generic././.

You can also use wildcards or absolute paths:

require("./stuff/*")
require("/usr/share/among/us.lua")

锁屏

在 Hyprland 里，推荐用官方的 hyprlock 锁屏。它就是 Hyprland 配套的 GPU 加速锁屏程序。(Hypr Land 维基1)

先安装：

sudo pacman -S hyprlock

然后创建配置文件：

mkdir -p ~/.config/hypr
nvim ~/.config/hypr/hyprlock.conf

最简单可以先写：

background {
    monitor =
    color = rgba(30, 30, 30, 1.0)
}

input-field {
    monitor =
    size = 300, 50
    position = 0, 0
}

现在新版 hyprlock 如果找不到配置文件，会直接退出而不会锁屏，所以这个文件需要存在。(Hypr Land 维基1)

然后直接测试：

hyprlock

输入你的 Linux 用户密码即可解锁。

给你绑定 SUPER + L

你现在用的是 hyprland.lua，直接加入：

hl.bind("SUPER + L", hl.dsp.exec_cmd("hyprlock"))

设置默认工作空间

因为上班我主要用外接的4K显示器，笔记本自带的屏幕我只是用来辅助。默认配置，笔记本自带的屏幕会占用1，用起来会不顺手。

-- 笔记本内屏默认7
hl.workspace_rule({
	workspace = "7",
	monitor = "eDP-1",
	default = true,
	persistent = true,
})

-- 外接显示屏默认为1
hl.workspace_rule({
	workspace = "1",
	monitor = "HDMI-A-1",
	default = true,
	persistent = true,
})

动态壁纸

yay -S mpvpaper

mpvpaper -o "no-audio loop" '*' /home/itkey/.config/wallpaper/【哲风壁纸】卡通-水面-治愈_2850x1604.mp4

如果只在外接显示器上显示则

mpvpaper -o "no-audio loop" 'HDMI-A-1' /home/itkey/.config/wallpaper/【哲风壁纸】人物剪影-开阔-旷野.mp4

好看是好看，但是CPU占用明显更高。所以我还是停用了。

参考：

https://wiki.hypr.land/useful-utilities/wallpapers/

微信截图

-- 微信截图：将 Alt+A 转发给微信窗口
hl.bind("ALT + A", hl.dsp.pass({ window = "class:^(wechat)$" }))

微信截图基本够用了，我这里配置一下。

但是我感觉用起来没有X11中那么流畅，必须等一会儿才会显示出来截图的框。

有时还不灵，必须点一下微信窗口的的截图。然后又灵了。

Satty 截图

sudo pacman -S satty

配置

hl.bind("Print", hl.dsp.exec_cmd('grim - | satty -f - --copy-command wl-copy -o "~/Pictures/Screenshots/%Y%m%d_%H%M%S.png"'))

用起来操作逻辑与平时用的截图软件不一样，它是把整个屏幕图片直接截图下来，然后在修改。感觉像是图片编辑软件一样。

至少稳定，不像微信截图那样时好时坏的。

通知字体过大的问题

• Edited ~/.config/dunst/dunstrc (+2 -6)

     2
     3 -# 修改字体
     4 -font = Monospace 36
     3 +# 通知字号使用 11pt，显示器缩放由 Dunst 自动处理。
     4 +font = Monospace 11

自动熄屏

sudo pacman -S hypridle

~/.config/hypr/hypridle.conf

内容如下：

# 空闲 10 秒后关闭显示器，检测到键盘或鼠标活动后自动恢复。
# 这里只关闭屏幕，不自动锁屏或挂起系统。
listener {
    timeout = 10
    on-timeout = hyprctl dispatch 'hl.dsp.dpms({ action = "disable" })'
    on-resume = hyprctl dispatch 'hl.dsp.dpms({ action = "enable" })'
}

开机启动在加入

hl.exec_cmd("systemctl --user start hypridle.service")

实测有效。