hypr-dynamic-cursors 是一款 Hyprland 动态光标插件，它模拟真实物体被拖动时的物理效果，让光标随移动方向倾斜、旋转或拉伸，并支持摇动鼠标放大光标（shake to find）。本文是一份 hyprpm 安装快速上手教程：只需 2 条命令，3 分钟即可完成 Hyprland 动态光标插件安装并上手配置。

🖱️ 功能速览：这个插件能做什么？

安装后你会得到两组核心能力：

放大时还能通过 hyprcursor 加载高分辨率光标贴图，细节可参考 README.md 中的 hyprcursor 章节。

⚙️ 安装前检查：30 秒确认系统兼容

Hyprland 动态光标插件 hyprpm 安装前，先确认以下 3 个条件（不满足第 1 条插件会静默失效）：

• 架构：仅支持x86_64（插件依赖 Hyprland 的 function hooks）。不确定也没关系，绝大多数桌面机器都符合
• Hyprland 版本：v0.41.2及以上。用hyprctl version查看当前版本
• hyprpm：Hyprland 官方插件管理器，随新版 Hyprland 自带，hyprpm --version可验证

⚠️ 注意：main分支的插件一般跟踪 Hyprland 开发版（-git）构建，版本不匹配时加载会报 version mismatch，见下文排查章节。

⚡ hyprpm 一键安装：只需 2 条命令

打开终端，依次执行：

hyprpm add https://gitcode.com/gh_mirrors/hy/hypr-dynamic-cursors hyprpm enable dynamic-cursors

第 1 条命令会下载并构建插件（首次需等待编译完成），第 2 条命令启用插件并由 hyprpm 自动写入开机自启配置。执行完成后，插件dynamic-cursors会随 Hyprland 会话自动加载。

验证插件已加载

hyprctl plugin list

输出中出现dynamic-cursors即安装成功。此时移动鼠标，你应该能感觉到光标开始"活"起来了 🎉

🎛️ 快速上手：基础配置与模式切换

所有配置都放在 Hyprland 配置的plugin.dynamic_cursors段中。按官方建议，用if块包裹，避免插件未加载时配置报错：

if hl.plugin.dynamic_cursors then hl.config { plugin = { dynamic_cursors = { -- 切换模拟模式：tilt / rotate / stretch / none mode = "tilt", -- shake to find 相关 shake = { enabled = true, -- 摇动找光标，默认开启 base = 4.0, -- 摇动开始时的放大倍数 timeout = 2000, -- 停止摇动后保持放大的时长（ms） }, }}} end

常用可调参数：

修改配置后执行hyprctl reload立即生效，无需重启桌面。完整默认值清单见 README.md 的 configuration 章节，各项配置项在 src/config/ConfigManager.cpp 中注册。

🔍 Shake to Find：最快找回光标的方法

多显示器环境下光标"失踪"是常态。本插件默认开启 shake to find：快速来回摇动鼠标，光标会立刻放大并短暂保持，效果类似 KDE Plasma 和 macOS 的同类功能。

• 只用放大、不要动态效果：把mode设为"none"
• 放大支持 dispatcher 触发，例如绑定快捷键放大 2 秒：hl.plugin.dynamic_cursors.dsp_magnify({ duration = 2000, size = 4.0 })

🛠️ 常见安装问题排查

版本冲突提示来自加载时的哈希校验逻辑，参考 src/main.cpp。

🧩 进阶：更新、卸载与源码构建

hyprpm update dynamic-cursors # 更新插件 hyprpm remove dynamic-cursors # 卸载插件

想自己编译调试的话，clone 仓库（地址：https://gitcode.com/gh_mirrors/hy/hypr-dynamic-cursors）后执行 Makefile 提供的命令：

make load # 编译并加载到当前 Hyprland 会话

NixOS 用户则推荐通过仓库自带的 flake.nix 或 nixpkgs 中的现成包安装，具体步骤见 README.md 的 NixOS 折叠章节。

✅ 总结

• hypr-dynamic-cursors 是一款让 Hyprland 光标"更像真实物体"的动态光标插件，附带实用的 shake to find 找光标功能
• hyprpm 安装只需 2 条命令：hyprpm add+hyprpm enable dynamic-cursors，3 分钟即可上手
• 推荐先体验默认的tilt模式和 shake 放大，再按需切换rotate/stretch并微调参数
• 记住两个前提：x86_64架构、Hyprland ≥ v0.41.2

现在，试着快速甩动几下鼠标，看看你的光标"活"过来的样子吧 ✨