企业官网建设流程全解析

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-workspaces

split-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

版本与插件分支的对应关系记录在 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()传入一个参数表。逐项对照如下：

两点注意：

• 类型变化：C++ 配置用0/1表示布尔值，Lua 版本改用真正的true/false；
• hy3 支持简化：C++ 版需要手动写enable_hy3 = 1，Lua 版会自动检测 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, 1

Lua 版本用循环优雅替代，一行配置覆盖全部工作区：

local mainMod = "SUPER" for i = 1, smw.get_amount_of_workspaces() do local n = tostring(i) if n == "10" then n = "0" end -- 第 10 个工作区绑定到 SUPER+0 hl.bind(mainMod .. " +" .. n, smw.workspace(n)) -- 切换 hl.bind(mainMod .. " + SHIFT +" .. n, smw.move_to_workspace_silent(n)) -- 静默移动窗口 end

指令（dispatcher）完整对照表

几个实用细节：

• 所有切换函数都支持+N/-N相对参数，且支持首尾环绕；
• Lua 版新增"empty"参数：smw.workspace("empty")可直接跳到当前显示器第一个空工作区；
• 旧指令split-cycleworkspacesnowrap没有独立 API 了，只需设置enable_wrapping = false。

迁移后清理与验证清单

迁移完成后，记得做好收尾，避免两套配置打架：

1. 删除hyprland.conf中整个plugin { split-monitor-workspaces { ... } }块；
2. 删除自动加载 C++ 插件的exec-once = hyprpm reload -n行；
3. 删除所有旧的split-*bind 行（已被hl.bind循环替代）；
4. 重载配置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 兼容。

总结

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