hyprland

Hyprland 文档

Hyprland Wayland 合成器的完整参考资料，由 https://wiki.hypr.land/ 上的官方 Wiki 自动生成。

references/ 目录包含来自 https://github.com/hyprwm/hyprland-wiki 的完整、未经修改的 Wiki Markdown，每日更新。

如何使用

1. 根据用户的问题确定主题，并从下方表格中读取对应的参考文件。
2. 依据这些文件作答。如需更多详情，请从“实时获取”中的原始 GitHub URL 获取最新文档。
3. 从 Hyprland 0.55 开始，配置使用 Lua（~/.config/hypr/hyprland.lua）：hl.config({...})、hl.bind(...)、hl.monitor({...})、hl.window_rule({...})、hl.on(...)。旧版 hyprlang 格式（hyprland.conf）已弃用。如有疑问，请使用 hyprctl version 查看用户的版本。
4. 对于 Hyprland 0.54 及更早版本，请使用 hyprlang 语法，并引导用户访问版本对应的 Wiki：https://wiki.hypr.land/0.54.0/（此处的参考文件对应当前 Lua 文档）。
5. 拆分配置使用 Lua require("subdir/file")，而不是旧版 source = 关键字。
6. 对于 NixOS 用户，请注意 hyprpm 不受 Nix 支持——插件请使用 Home Manager 或 NixOS 模块。
7. 排查问题时，请先查看 references/faq.md。

参考文件

配置

主题	文件
配置文件基础、Lua 语法、require、LSP 存根	references/start.md
变量／选项（通用、装饰、输入、杂项等）	references/variables.md
按键绑定（hl.bind、标志、子映射）	references/binds.md
调度器（hl.dsp.*、hl.dispatch）	references/dispatchers.md
窗口规则和图层规则	references/window-rules.md
显示器配置	references/monitors.md
自动启动（hyprland.start 事件）	references/autostart.md
动画和贝塞尔曲线	references/animations.md
工作区规则和智能间距	references/workspace-rules.md
环境变量	references/environment-variables.md
布局（dwindle、master、scrolling、monocle、自定义）	references/layouts.md
Lua 脚本、事件、定时器（hl.on、hl.exec_cmd）	references/lua-scripting.md
按设备配置输入	references/devices.md
通知 API	references/notifications.md
性能调优	references/performance.md
XWayland	references/xwayland.md
屏幕撕裂	references/tearing.md
多 GPU	references/multi-gpu.md
虚拟 GPU	references/virtual-gpu.md
权限	references/permissions.md
手势	references/gestures.md
Systemd 集成（graphical-session.target）	references/systemd.md
命名约定（工作区、显示器、窗口选择器）	references/naming-conventions.md
Lua 代码片段和示例配置	references/code-snippets.md

工具

主题	文件
hyprctl CLI 用法（eval、repl、batch）	references/hyprctl.md
IPC 套接字和事件	references/ipc.md

Hypr 生态

主题	文件
Hyprlock（屏幕锁定）	references/hyprlock.md
Hypridle（空闲管理）	references/hypridle.md
Hyprpaper（壁纸）	references/hyprpaper.md
Hyprlauncher（应用启动器）	references/hyprlauncher.md
Hyprpicker（颜色选择器）	references/hyprpicker.md
Hyprsunset（蓝光滤镜）	references/hyprsunset.md
Hyprcursor（光标主题）	references/hyprcursor.md
XDPH（xdg-desktop-portal-hyprland）	references/xdph.md
Hyprpolkitagent（polkit 身份验证）	references/hyprpolkitagent.md
Hyprshutdown（关机实用工具）	references/hyprshutdown.md
Hyprsysteminfo（系统信息）	references/hyprsysteminfo.md
Hyprpwcenter（电源管理）	references/hyprpwcenter.md
Hyprland Qt 支持	references/hyprland-qt-support.md
开发库（hyprtoolkit、hyprlang、hyprutils、aquamarine 等）	references/hypr-libraries.md

插件

主题	文件
插件使用与开发	references/plugins.md

特定平台

主题	文件
NixOS / Nix / Home Manager	references/nix.md
Nvidia 设置	references/nvidia.md

帮助

主题	文件
常见问题与故障排除	references/faq.md
入门 / 安装	references/getting-started.md
实用工具（状态栏、启动器、截图、systemd 等）	references/useful-utilities.md
崩溃与错误	references/crashes-and-bugs.md
为 Hyprland 做贡献	references/contributing.md

实时获取

参考文件内容不足时，请从 GitHub 原始文件获取最新文档：

https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/<section>/<page>.md

路径均为小写。章节索引页面为 _index.md。例如：

• https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/config-options.md
• https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/advanced-configuration/using-hyprctl.md
• https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/hypr-ecosystem/user/hyprlock.md
• https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/nix/installing-hyprland-on-nixos.md

每个参考文件顶部的 `` 标头会标明对应的 wiki 章节。

快速参考（Hyprland 0.55+，Lua 配置）

配置文件位置

~/.config/hypr/hyprland.lua（或 $XDG_CONFIG_HOME/hypr/hyprland.lua，使用 Hyprland --config 覆盖）

选项

hl.config({
    general = {
        border_size = 2,
        gaps_in = 5,
    },
})

允许多次调用 hl.config()；每次调用只会更新传入的配置项。

按键绑定

hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("firefox"))
hl.bind("SUPER + X", function()
    hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
end)

自动启动

hl.on("hyprland.start", function()
    hl.exec_cmd("waybar & hyprpaper")
end)

窗口规则

hl.window_rule({
    match = { class = "firefox" },
    opacity = 0.9,
    float = true,
})

显示器

hl.monitor({
    output = "DP-1",
    mode = "1920x1080@144",
    position = "0x0",
    scale = 1,
})

拆分配置

require("conf/binds")      -- ~/.config/hypr/conf/binds.lua

hyprctl 运行时控制

hyprctl reload
hyprctl eval 'hl.config({ general = { border_size = 3 } })'
hyprctl repl               # interactive Lua REPL
hyprctl --batch "..."

旧版（Hyprland 0.54 及更早版本，hyprlang）

旧式 ~/.config/hypr/hyprland.conf：

bind = MODS, key, dispatcher, params
general {
    border_size = 2
}
monitor = name, resolution@rate, position, scale

完整旧版文档：https://wiki.hypr.land/0.54.0/