split-monitor-workspaces弃用C插件指南从hyprland.conf到Lua API的完整迁移路径【免费下载链接】split-monitor-workspacesA small lua package for Hyprland to provide awesome-like workspace behavior项目地址: https://gitcode.com/gh_mirrors/sp/split-monitor-workspacessplit-monitor-workspaces 是 Hyprland 的开源工作区插件能让每个显示器拥有独立编号的工作区类似 awesome/dwm 行为。官方已宣布弃用其 C 插件推荐迁移到全新的 Lua API 版本——本指南带你完整走一遍迁移路径检查版本、克隆安装、配置项对照、按键绑定重写全程不到 10 分钟。⚠️ 为什么 C 插件必须弃用C 插件的版本支持范围是Hyprland v0.38.1 ~ v0.56.x最新 git 版本已不再支持。更直观的信号是C 插件在每次配置重载时都会弹出一条弃用通知源码里写得很清楚——The C plugin has been deprecated, please use the Lua package instead.参见 src/main.cpp。此外C 插件将在 Hyprland 0.57.0 发布后正式停止维护。而新的 Lua 包功能完全一致且是官方主推方案要求Hyprland 0.55.0。迁移前检查你的 Hyprland 版本够新吗迁移的第一步是确认版本。在终端执行hyprctl version你的 Hyprland 版本建议操作 0.55.0✅ 直接迁移到 Lua 包v0.38.1 ~ 0.54.x建议先升级 Hyprland再迁移0.56.x最后一个支持 C 的版本尽快迁移0.57.0 后 C 插件将弃用版本与插件分支的对应关系记录在 hyprpm.toml 中迁移后请根据你的 Hyprland 版本选择对应的 release 分支。快速安装3 步完成 Lua 包部署第 1 步克隆仓库到 Hyprland 插件目录mkdir -p ~/.config/hypr/plugins cd ~/.config/hypr/plugins git clone https://gitcode.com/gh_mirrors/sp/split-monitor-workspaces第 2 步在 Hyprland 的 Lua 配置中加入加载路径并导入模块package.path package.path .. ;./?.lua;./?/init.lua local smw require(plugins.split-monitor-workspaces)第 3 步调用setup()完成初始化smw.setup({ workspace_count 5, -- 每个显示器创建 5 个持久工作区 })入口逻辑位于 lua/split-monitor-workspaces.lua完整可运行的示例配置见 docs/example.lua。配置项对照表hyprland.conf 如何改成 smw.setup()这是迁移的核心部分。C 插件在hyprland.conf的plugin {}块里配置Lua 版本统一改由smw.setup()传入一个参数表。逐项对照如下hyprland.confC 插件Lua 版本smw.setup参数说明count 5workspace_count 5每个显示器绑定的工作区数默认 10keep_focused 1keep_focused true重载时保持当前工作区焦点enable_notifications 1enable_notifications true初始化时弹出通知enable_persistent_workspaces 1enable_persistent_workspaces true空工作区也保持存活enable_wrapping 1enable_wrapping true首尾循环切换link_monitors 0link_monitors falseGnome 式全显示器同步切换monitor_priority DP-1, DP-2monitor_priority { DP-1, DP-2 }显示器编号优先级max_workspaces DP-2, 3max_workspaces { [DP-2] 3 }按显示器覆盖工作区数量两点注意类型变化C 配置用0/1表示布尔值Lua 版本改用真正的true/falsehy3 支持简化C 版需要手动写enable_hy3 1Lua 版会自动检测 hy3 插件是否加载并启用其 dispatchers无需任何配置。所有默认值定义在 lua/globals.lua迁移时可逐一核对。旧版 C 插件的完整配置说明保留在 docs/cpp-plugin.md 供查阅。按键绑定迁移从 bind 到 hl.bind()C 插件时代你在hyprland.conf里写下一长串bind行# hyprland.conf旧 bind $mainMod, 1, split-workspace, 1 bind $mainMod, 2, split-workspace, 2 bind $mainMod SHIFT, 1, split-movetoworkspacesilent, 1Lua 版本用循环优雅替代一行配置覆盖全部工作区local mainMod SUPER for i 1, smw.get_amount_of_workspaces() do local n tostring(i) if n 10 then n 0 end -- 第 10 个工作区绑定到 SUPER0 hl.bind(mainMod .. .. n, smw.workspace(n)) -- 切换 hl.bind(mainMod .. SHIFT .. n, smw.move_to_workspace_silent(n)) -- 静默移动窗口 end指令dispatcher完整对照表功能C 插件指令Lua API切换到工作区split-workspacesmw.workspace()移动窗口到工作区split-movetoworkspacesmw.move_to_workspace()静默移动窗口split-movetoworkspacesilentsmw.move_to_workspace_silent()循环切换工作区split-cycleworkspacessmw.cycle_workspaces()窗口移到下一/上一显示器split-changemonitorsmw.change_monitor()静默移动不换焦点split-changemonitorsilentsmw.change_monitor_silent()回收迷路的窗口split-grabroguewindowssmw.grab_rogue_windows()几个实用细节所有切换函数都支持N/-N相对参数且支持首尾环绕Lua 版新增empty参数smw.workspace(empty)可直接跳到当前显示器第一个空工作区旧指令split-cycleworkspacesnowrap没有独立 API 了只需设置enable_wrapping false。迁移后清理与验证清单迁移完成后记得做好收尾避免两套配置打架删除hyprland.conf中整个plugin { split-monitor-workspaces { ... } }块删除自动加载 C 插件的exec-once hyprpm reload -n行删除所有旧的split-*bind 行已被hl.bind循环替代重载配置hyprctl reload看到 Initialized successfully! 通知即迁移成功 。验证方法按下SUPER 1~5应在当前显示器内切换独立编号的工作区SUPER SHIFT 数字静默移动窗口。若使用了 Waybar其hyprland/workspaces模块可直接配合smw.cycle_workspaces()实现滚轮循环工作区配置示例见 README.md。常见坑速查Hyprland 是 release 版在插件仓库内执行git fetch -Ppft git checkout release/0.55.x版本号对应你的 Hyprland 大版本否则可能加载失败Omarchy 用户需先unbindOmarchy 自带的code:10~code:19工作区绑定再写入自己的hl.bind详细说明见 docs/cpp-plugin.md找不到模块确认package.path已包含插件目录入口文件 init.lua 会自动转发到lua/split-monitor-workspaces模块Hyprland 每次大版本更新后记得git pull拉取插件更新并切换到新的 release 分支保证 ABI 兼容。总结迁移步骤要点检查版本Hyprland 0.55.0安装克隆到~/.config/hypr/plugins并require配置plugin {}块 →smw.setup()参数表绑定长串bind行 →for循环 hl.bind清理删除split-*指令与 hyprpm 加载行C 插件的弃用不是功能缩水而是更现代的实现方式Lua 包自动处理 hy3 集成、支持empty工作区、配置重载时自动重新映射显示器。完成迁移后你将获得一个更简洁、面向未来的 Hyprland 多显示器工作区体验。【免费下载链接】split-monitor-workspacesA small lua package for Hyprland to provide awesome-like workspace behavior项目地址: https://gitcode.com/gh_mirrors/sp/split-monitor-workspaces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考