Hyprmod 设置指南

前言

Hyprland 作为一款现代化的 Wayland 动态平铺窗口管理器，以其高度可定制和轻量化著称。而 Hyprmod 则是它的一个强大模块，提供了额外的布局、动画以及高级输入处理能力。本文将从 安装、基本配置、常见使用场景 以及 故障排查 四个方面，手把手带你玩转 Hyprmod。

一、安装 Hyprmod

1. 确保 Hyprland 已安装

   1 2	pacman -S hyprland # Arch 系统 sudo apt install hyprland # Debian/Ubuntu 系统（若官方仓库提供）

   若系统自带的版本过旧，请参考官方 GitHub 的 Build 指南自行编译最新分支。

2. 获取 Hyprmod 源码

   1 2	git clone https://github.com/hyprwm/hyprmod.git $HOME/hyprmod cd $HOME/hyprmod

3. 编译并安装

   1 2 3

   meson setup build --prefix=/usr/local ninja -C build sudo ninja -C build install

   该过程会生成 hyprmod.so 动态库，默认安装到 /usr/local/lib。

二、基本配置

Hyprmod 通过 hyprland.conf 中的 plugin 指令加载。打开你的配置文件（通常在 ~/.config/hypr/hyprland.conf），添加以下行：

1

plugin = /usr/local/lib/hyprmod.so

随后在同一文件中可以使用 Hyprmod 暴露的属性。例如，启用 “滚动平滑”：

1
2

# 平滑滚动开关
plugin:hyprmod:scroll_smooth = true

常用选项速查表

三、进阶使用场景

1. 自定义布局插件

Hyprmod 支持 Lua 脚本自定义布局。创建 ~/.config/hypr/hyprmod/layouts/mygrid.lua，示例代码如下：

1
2
3
4
5
6
7
8

local hypr = require('hyprmod')

function mygrid(arr)
    -- 将所有窗口均匀分布在 2×2 网格中
    hypr.tile_grid(arr, 2, 2)
end

hypr.register_layout('mygrid', mygrid)

在 hyprland.conf 中绑定快捷键来切换布局：

1

bind = $mod, L, exec, hyprctl --reload && hyprmod layout mygrid

2. 动画效果增强

通过 window_animate 与 focus_fade 可以让窗口出现、消失时拥有玻璃碎片般的动画。结合 border_radius，能够打造类似 macOS 的圆角玻璃窗口。

3. 输入法优化

Hyprmod 为 fcitx5、ibus 提供了键盘焦点自动切换的钩子。打开配置：

1

plugin:hyprmod:ime_sync = true

这样在切换窗口焦点时，输入法会自动跟随，无需手动切换。

四、故障排查

1. 插件加载失败
   • 检查路径是否正确（/usr/local/lib/hyprmod.so）
   • 确认 Hyprland 启动日志中没有 “cannot open shared object file” 错误。
2. 动画卡顿
   • 确认显卡驱动已正确加载，glxinfo | grep OpenGL 应显示硬件渲染。
   • 关闭 window_animate 试验是否是动画本身导致。
3. Lua 脚本报错
   • 在终端执行 hyprctl plugin hyprmod exec mygrid.lua 查看报错信息。
   • 确保脚本文件 UTF-8 编码且没有 Windows 换行符。

五、性能调优与常见问题

• CPU 占用：开启大量动画会增加 compositor 的负载。可以通过调低 focus_fade 或关闭 window_animate 来降低 CPU 使用率。
• 多显示器：Hyprmod 的布局插件默认在所有显示器上生效。若只想在特定显示器使用自定义布局，请在 Lua 脚本中判断 monitor.id。
• 快捷键冲突：确保 bind 指令中的键位未被其他插件占用，否则会导致无法触发。

结语

Hyprmod 为 Hyprland 注入了更细腻的交互体验和可玩性。只要按照本文步骤完成安装与配置，你就可以在日常工作流中感受到更流畅的窗口切换、更炫目的动画以及更智能的输入法协同。若遇到新问题，欢迎到 Hyprland 的 GitHub Discussions 发帖求助，社区的开发者们通常会很快给出答案。

本文由 BOSH 的博客助手 HerMes 整理 🚀