hyprland

用途

本技能用于在用户询问 Hyprland 配置、hyprland.lua、hyprland.conf、Hyprland Lua 配置、hyprctl 等相关话题时提供参考。Hyprland 是一个基于 Wayland 的平铺式合成器，本技能文档由官方 wiki（https://wiki.hypr.land/）自动生成，references/ 目录包含来自 https://github.com/hyprwm/hyprland-wiki 的完整、未修改的 wiki Markdown 内容，每日更新。

主要能力

技能按主题组织参考文件，覆盖以下方面：

配置：配置文件基础、Lua 语法、require、LSP 存根（references/start.md）；变量/选项（references/variables.md）；键位绑定（references/binds.md）；调度器（references/dispatchers.md）；窗口规则与图层规则（references/window-rules.md）；显示器配置（references/monitors.md）；自启动（references/autostart.md）；动画与贝塞尔曲线（references/animations.md）；工作区规则与智能间隙（references/workspace-rules.md）；环境变量（references/environment-variables.md）；布局（references/layouts.md）；Lua 脚本、事件、定时器（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 集成（references/systemd.md）；命名约定（references/naming-conventions.md）；Lua 代码片段与示例配置（references/code-snippets.md）。
工具：hyprctl CLI 用法（references/hyprctl.md）；IPC 套接字与事件（references/ipc.md）。
Hypr 生态：Hyprlock、Hypridle、Hyprpaper、Hyprlauncher、Hyprpicker、Hyprsunset、Hyprcursor、XDPH、Hyprpolkitagent、Hyprshutdown、Hyprsysteminfo、Hyprpwcenter、Hyprland Qt 支持、开发库等。
插件：插件使用与开发（references/plugins.md）。
平台特定：NixOS / Nix / Home Manager（references/nix.md）；Nvidia 设置（references/nvidia.md）。
帮助：FAQ 与排障（references/faq.md）；入门/安装（references/getting-started.md）；实用工具（references/useful-utilities.md）；崩溃与 bug（references/crashes-and-bugs.md）；为 Hyprland 贡献（references/contributing.md）。

使用方式

根据用户问题识别主题，从上述表格中读取匹配的参考文件，并基于这些文件作答。如需更多细节，可从 Live Fetching 中的 raw GitHub URL 获取最新文档。

自 Hyprland 0.55 起，配置为 Lua（~/.config/hypr/hyprland.lua），使用 hl.config({...})、hl.bind(...)、hl.monitor({...})、hl.window_rule({...})、hl.on(...) 等。旧的 hyprlang 格式（hyprland.conf）已弃用。如有疑问，可用 hyprctl version 检查用户版本。

对于 Hyprland 0.54 及更早版本，使用 hyprlang 语法，并引导用户访问版本化 wiki：https://wiki.hypr.land/0.54.0/（此处参考文件跟踪当前 Lua 文档）。

拆分配置使用 Lua require("subdir/file")，而非旧的 source = 关键字。

对于 NixOS 用户，注意 hyprpm 在 Nix 上不受支持——插件请使用 Home Manager 或 NixOS 模块。

排障时，先检查 references/faq.md。

实时获取：当参考文件不足时，从 raw GitHub 获取最新文档：https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/<section>/<page>.md。路径为小写，章节索引页为 _index.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/

适用场景

适用于需要查询 Hyprland 合成器配置语法、键位绑定、窗口规则、显示器设置、生态组件用法、插件、平台特定安装（NixOS、Nvidia）以及排障的用户。

限制

本技能为文档参考，不包含 Hyprland 本身的安装或运行。部分主题（如具体收费、价格、平台支持范围）在资料中暂未提供。