AI 可能出错，请核对原文 在独立页面打开
问文档
目录

Hyprland Lua：多屏坐标、键位与验证

5 分钟
本页目录

本文使用 Hyprland 0.55 系列的 hyprland.lua 配置形式。旧版 hyprland.conf 的关键词和窗口规则语法不能直接混入 Lua；先确认已安装版本，再打开相应版本的官方文档。Lua 配置入口

下面的片段用于逐项合并到配置中，不是覆盖整个桌面环境的一键安装文件。

先确认正在连接哪个会话

在 Hyprland 会话内的终端运行：

hyprctl version
hyprctl monitors -j

第一条确认运行中合成器版本，第二条查看显示器名称、描述、模式与缩放。若报告 HYPRLAND_INSTANCE_SIGNATURE 未设置，说明当前 Shell 没有连接到合成器实例；这不等于机器上没有安装 Hyprland。

不要从另一台机器照抄 DP-1。连接器名称会随接线变化，使用 desc: 匹配设备描述时也应确认描述足够唯一；同型号显示器缺少唯一序列信息时仍可能冲突。

建立回退显示规则

hl.monitor({
    output = "",
    mode = "preferred",
    position = "auto",
    scale = "auto",
})

这为未单独匹配的显示器提供一般规则。确认能正常显示后，再增加具体屏幕配置。先调整一块屏幕并验证，避免同时更改刷新率、旋转、缩放和连接方式后无法归因。

物理像素如何变成逻辑坐标

一块 3840×2160 的屏幕使用 1.5 倍缩放时，未旋转的逻辑尺寸是 2560×1440。旋转 90° 后宽高互换，成为 1440×2560。布局中的位置使用这个逻辑空间，不是原始物理像素。

考虑左侧上下两块横屏、右侧一块竖屏：

屏幕物理模式缩放与变换逻辑尺寸左上角
A：左上3840×21601.5，180°2560×14400, 0
B：左下3840×21601.5，正常2560×14400, 1440
C：右侧3840×21601.5，90°1440×25602560, 0

B 的 y 坐标等于 A 的逻辑高度；C 的 x 坐标等于左列宽度。整个布局包围盒是 4000×2880，右下角会留下 1440×320 的非显示区域。鼠标跨边缘的位置和窗口排列应按这些关系判断。

下面使用示例连接器名；改成 hyprctl monitors -j 查到的值，并确认模式在设备支持列表中：

hl.monitor({
    output = "DP-1", mode = "3840x2160@60",
    position = "0x0", scale = 1.5, transform = 2,
})
hl.monitor({
    output = "DP-2", mode = "3840x2160@60",
    position = "0x1440", scale = 1.5,
})
hl.monitor({
    output = "DP-3", mode = "3840x2160@60",
    position = "2560x0", scale = 1.5, transform = 1,
})

本地实例曾采用混合 160/60/60Hz 和按屏 VRR 策略。混合刷新率、带宽、显卡驱动和显示引擎资源都会影响稳定性；“换一根更高规格线就一定解决”不能作为通用结论。

窗口与工作区的键位

local mainMod = "SUPER"
hl.bind(mainMod .. " + T", hl.dsp.exec_cmd("ghostty"))
hl.bind(mainMod .. " + Q", hl.dsp.window.close())
hl.bind(mainMod .. " + F", hl.dsp.window.fullscreen())
hl.bind(mainMod .. " + H", hl.dsp.focus({ direction = "left" }))
hl.bind(mainMod .. " + J", hl.dsp.focus({ direction = "down" }))
hl.bind(mainMod .. " + K", hl.dsp.focus({ direction = "up" }))
hl.bind(mainMod .. " + L", hl.dsp.focus({ direction = "right" }))

先确认 ghostty 位于会话的 PATH。终端里能执行的程序，不一定能被合成器或 systemd 用户服务找到，因为交互 Shell 可能额外修改了 PATH。

工作区切换与窗口循环是不同任务。例如：

hl.bind("ALT + Tab", hl.dsp.focus({ workspace = "m+1" }))
hl.bind("ALT + grave", hl.dsp.window.cycle_next())

前一条使用当前显示器上的相对工作区规则，后一条循环窗口。是否符合习惯要在多屏、多工作区场景中验证，不应只在单个窗口上测试。

规则、重载与恢复

添加应用规则前，用 hyprctl clients -j 确认实际 class/title。标题可能随文档、浏览器标签或语言变化；将规则范围写得过宽，会影响所有匹配窗口。

保存后，在可用终端中执行：

hyprctl reload
hyprctl configerrors

检查配置错误，再分别测试打开终端、移动焦点和显示器布局。Lua 语法能解析，不代表 hl API 参数和设备模式有效；运行中的配置错误必须另查。

如果图形界面失去可操作性，从已准备好的 TTY 或远程入口还原配置，再重新进入会话。不要在没有恢复入口时同时修改登录启动与全部显示器规则。

显示故障的检查顺序

先用首选模式和默认缩放验证单屏，再恢复多屏；先保持固定刷新率，再测试 VRR；最后检查全屏和 direct scanout 相关条件。每次记录连接器、模式、驱动、触发动作和日志时间。

颜色与外壳没有必要在这里重复配置，分别继续阅读 Matugen 与 Quickshell。服务启动和环境变量问题见会话排障。

链接预览

新窗口打开