From f176124c1897d1f8394c48464602bda3e299abd4 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 20:32:47 +0800 Subject: [PATCH 01/13] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E9=BB=98=E8=AE=A4=E4=BB=A5=20Wayland=20?= =?UTF-8?q?=E5=90=AF=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 36b1e5c..4ca8bd0 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -6,8 +6,6 @@ 遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（XWayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。 -> SPlayer-Next 默认即以 XWayland 运行；若你或发行版启用了原生 Wayland 并遇到问题，用此参数可强制回退。 - 开发环境： ```bash @@ -32,18 +30,6 @@ pnpm dev -- --ozone-platform=x11 ``` 4. 保存退出。 -## 原生 Wayland（可选） - -原生 Wayland 渲染更清晰、HiDPI / 分数缩放表现更好，但下面的窗口能力会更受限，且个别环境可能出现闪屏 / 卡死——**遇到问题请按上文回退 X11**。 - -启用方式（命令行）： - -```bash -ELECTRON_OZONE_PLATFORM_HINT=auto ./SPlayer-Next-*.AppImage -# 或 -./SPlayer-Next-*.AppImage --ozone-platform-hint=auto -``` - ## 已知的窗口限制 Wayland 出于安全考虑，不允许应用读取 / 设置全局屏幕坐标，并对置顶、穿透、透明无边框窗口有更多约束。这会影响 SPlayer-Next 的以下功能： From 6479edc0d33e6945a891499cd9674e3b28f775bb Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 20:34:50 +0800 Subject: [PATCH 02/13] =?UTF-8?q?docs:=20=E8=A7=84=E8=8C=83=20Xwayland=20?= =?UTF-8?q?=E7=9A=84=E6=8B=BC=E5=86=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 4ca8bd0..e7cd63f 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -2,9 +2,9 @@ 在 Wayland 会话下，部分**窗口相关功能**可能受限，个别环境甚至会出现画面闪烁、花屏乃至系统卡死。这是 Electron / Chromium 在 Wayland 下的通用情况，并非应用本身的缺陷。 -## 首选方案：切回 XWayland +## 首选方案：切回 Xwayland -遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（XWayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。 +遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（Xwayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。 开发环境： From 11c9ad334c91afbb0a60cfb8fd35d121f94ad374 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 20:37:20 +0800 Subject: [PATCH 03/13] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=E8=B7=AF?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index e7cd63f..b96f174 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -26,7 +26,7 @@ pnpm dev -- --ozone-platform=x11 2. 复制到 `~/.local/share/applications/`； 3. 用文本编辑器打开，找到 `Exec=` 开头的行，在可执行文件后追加 `--ozone-platform=x11`，例如： ``` - Exec=/opt/SPlayer-Next/splayer-next --ozone-platform=x11 %U + Exec=/opt/SPlayer-Next/SPlayer-Next --ozone-platform=x11 %U ``` 4. 保存退出。 From 7dd729658e8e1003335046c038fd3a1b2a40282f Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 20:37:30 +0800 Subject: [PATCH 04/13] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E5=90=8D=E6=8F=90=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index b96f174..1066220 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -22,7 +22,7 @@ pnpm dev -- --ozone-platform=x11 **其他桌面环境** -1. 找到 SPlayer-Next 的 `.desktop` 文件（通常在 `/usr/share/applications/` 下）； +1. 找到 SPlayer-Next 的 `.desktop` 文件（通常在 `/usr/share/applications/` 下，文件名为 `top.imsyy.splayer_next.desktop`）； 2. 复制到 `~/.local/share/applications/`； 3. 用文本编辑器打开，找到 `Exec=` 开头的行，在可执行文件后追加 `--ozone-platform=x11`，例如： ``` From 0b305b7e7a7a6c3f067d1c78e29a3fd44ad51841 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 20:37:46 +0800 Subject: [PATCH 05/13] =?UTF-8?q?docs:=20=E4=BF=AE=E6=94=B9=20Wayland=20?= =?UTF-8?q?=E5=85=A8=E5=B1=80=E5=BF=AB=E6=8D=B7=E9=94=AE=E7=9A=84=E8=A1=A8?= =?UTF-8?q?=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 1066220..77e05dd 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -41,7 +41,7 @@ Wayland 出于安全考虑，不允许应用读取 / 设置全局屏幕坐标， | 窗口置顶（always-on-top） | 支持有限，悬浮窗可能无法保持置顶 | | 鼠标穿透（click-through） | 可能不生效 | | 悬停判定（全局光标位置） | Wayland 限制读取全局光标，悬停隐藏 / 交互可能不准 | -| 全局快捷键 | Wayland 下通常无法注册全局快捷键 | +| 全局快捷键 | Wayland 下可能无法注册全局快捷键 | > 具体表现因发行版与合成器（GNOME Mutter、KDE KWin、wlroots 等）而异。 From 1200141d76fc11dbbfd831f2c2ad31b72d3ddd18 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 21:04:53 +0800 Subject: [PATCH 06/13] =?UTF-8?q?docs:=20=E4=BF=AE=E6=94=B9=E7=AA=97?= =?UTF-8?q?=E5=8F=A3=E8=A7=84=E5=88=99=E7=9B=B8=E5=85=B3=EF=BC=8C=E6=8F=90?= =?UTF-8?q?=E4=BE=9B=E5=8F=AF=E7=9B=B4=E6=8E=A5=E5=AF=BC=E5=85=A5=E7=9A=84?= =?UTF-8?q?=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 62 ++++++++++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 77e05dd..d6931c5 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -45,17 +45,69 @@ Wayland 出于安全考虑，不允许应用读取 / 设置全局屏幕坐标， > 具体表现因发行版与合成器（GNOME Mutter、KDE KWin、wlroots 等）而异。 -## 桌面歌词的 KWin 窗口规则 +## 桌面歌词的窗口规则 -桌面歌词窗口使用固定的窗口标题 **`SPlayer-Next - Desktop Lyric`**。在 KDE（KWin）下可通过**窗口规则**按标题匹配，手动补齐 Wayland 下缺失的行为（如保持置顶等）： +桌面歌词窗口使用固定的窗口标题 **`SPlayer-Next - Desktop Lyric`** 以方便窗口规则匹配。 + +在 KDE（KWin）下可通过**窗口规则**按标题匹配，手动补齐 Wayland 下缺失的行为（如保持置顶等）： 1. 打开 **系统设置 → 窗口管理 → 窗口规则**，新建一条规则； -2. 在 **窗口匹配** 中，将 **窗口标题** 设为 `SPlayer-Next - Desktop Lyric`（精确或包含匹配）； +2. 在 **窗口匹配** 中，将 **窗口类** 设为 `top.imsyy.splayer_next`（精确匹配），将 **窗口标题** 设为 `SPlayer-Next - Desktop Lyric`（精确匹配）； 3. 添加需要的属性，例如： - - **保持在其他窗口之上**：设为「强制 / 是」； - - 可选 **无标题栏与边框**、固定 **位置** 与 **大小**； + - **窗口置顶**：设为 **强制**、**是**； + - 可选 **图层**：设为 **强制**、**叠加**（全屏游戏时窗口也在上方）； + - 可选 **虚拟桌面**：设为 **强制**、**所有桌面**（窗口同时处于所有虚拟桌面）； + - 可选 **跳过任务栏**、**跳过虚拟桌面切换器**、**跳过窗口切换器**：设为 **强制**、**是**（优化一些细节体验）； + - 可选固定 **位置** 与 **大小**； 4. 应用并保存。 +其它 DE/WM 也可参考此配置方法自行配置。 + +
+ +可直接导入的规则 + +> 这里提供了一些可直接导入的规则。欢迎 PR 补充你的 DE/WM + +KWin 规则 + +> 编者用的规则，我觉得挺好用的。如有更好的规则欢迎 PR + +```ini +[SPlayer Next 桌面歌词] +Description=SPlayer Next 桌面歌词 +above=true +aboverule=2 +desktops=\\0 +desktopsrule=2 +layer=overlay +layerrule=2 +skippager=true +skippagerrule=2 +skipswitcher=true +skipswitcherrule=2 +skiptaskbar=true +skiptaskbarrule=2 +title=SPlayer-Next - Desktop Lyric +titlematch=1 +wmclass=top.imsyy.splayer_next +wmclassmatch=1 +``` + +Niri 窗口规则 + +> 编者日常不使用 Niri，未经充分测试。如有更好的规则欢迎 PR + +```kdl +window-rule { + match app-id="top.imsyy.splayer_next" title="SPlayer-Next - Desktop Lyric" + open-floating true + default-layer "overlay" +} +``` + +
+ ## 第三方 / 外部 API 替代 如果在 Wayland 下内置悬浮窗体验不佳，可改用桌面环境原生的**面板 / 挂件类**第三方歌词组件：它们通过 SPlayer-Next 的 [外部 API（HTTP）](/api) 或 [WebSocket API](/socket) 获取当前播放与歌词，再由桌面环境自身负责显示，从而绕开 Electron 悬浮窗在 Wayland 下的限制。 From 808dc8cf5121939b08e807fb1d1aaebef2a7dcd1 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 22:34:55 +0800 Subject: [PATCH 07/13] =?UTF-8?q?docs:=20=E6=94=B9=E4=B8=80=E4=B8=8B?= =?UTF-8?q?=E6=A0=87=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index d6931c5..0d8b614 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -2,7 +2,7 @@ 在 Wayland 会话下，部分**窗口相关功能**可能受限，个别环境甚至会出现画面闪烁、花屏乃至系统卡死。这是 Electron / Chromium 在 Wayland 下的通用情况，并非应用本身的缺陷。 -## 首选方案：切回 Xwayland +## 使用 Xwayland 遇到花屏、闪烁、卡死或悬浮窗异常时，最稳妥的办法是让应用以 **X11（Xwayland）** 模式运行——在启动参数中加入 `--ozone-platform=x11`。 From 792ef9aec834c9af9b79bde203fcc6f55b833f9a Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Wed, 17 Jun 2026 23:05:13 +0800 Subject: [PATCH 08/13] =?UTF-8?q?docs:=20=E8=A7=84=E8=8C=83=E8=B7=AF?= =?UTF-8?q?=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/debug.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/debug.md b/docs/troubleshooting/debug.md index 060e0c7..9a3e61c 100644 --- a/docs/troubleshooting/debug.md +++ b/docs/troubleshooting/debug.md @@ -52,5 +52,5 @@ rd /s /q "%APPDATA%\SPlayer-Next" rm -rf ~/Library/Application\ Support/SPlayer-Next # Linux -rm -rf ~/.config/SPlayer-Next +rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/SPlayer-Next" ``` From 60b023388eb3b05afd6db39670f43c1097467c23 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Thu, 18 Jun 2026 19:01:11 +0800 Subject: [PATCH 09/13] =?UTF-8?q?docs:=20Xwayland=20=E7=9A=84=E5=85=A8?= =?UTF-8?q?=E5=B1=80=E5=BF=AB=E6=8D=B7=E9=94=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 0d8b614..3c33b1d 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -30,6 +30,12 @@ pnpm dev -- --ozone-platform=x11 ``` 4. 保存退出。 +> [!IMPORTANT] +> +> 即使切换回 Xwayland，全局快捷键仍可能无法正常生效。 +> +> 部分桌面环境对此有支持。如 KDE Plasma Wayland 可以在 **系统设置 → 应用程序权限 → 旧式 X11 应用程序支持** 中，将 **监听按键** 设置为 「**和上面一样，加上按住 Ctrl、Alt、Meta 等修饰键时按下的任何按键**」 + ## 已知的窗口限制 Wayland 出于安全考虑，不允许应用读取 / 设置全局屏幕坐标，并对置顶、穿透、透明无边框窗口有更多约束。这会影响 SPlayer-Next 的以下功能： From f8572b60b79c6011e09272e147747f2a4d2e6437 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Thu, 18 Jun 2026 21:47:27 +0800 Subject: [PATCH 10/13] =?UTF-8?q?docs:=20=E4=BB=A3=E7=A0=81=E5=9D=97?= =?UTF-8?q?=E8=AF=AD=E6=B3=95=E9=AB=98=E4=BA=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index 3c33b1d..be7f013 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -25,7 +25,7 @@ pnpm dev -- --ozone-platform=x11 1. 找到 SPlayer-Next 的 `.desktop` 文件（通常在 `/usr/share/applications/` 下，文件名为 `top.imsyy.splayer_next.desktop`）； 2. 复制到 `~/.local/share/applications/`； 3. 用文本编辑器打开，找到 `Exec=` 开头的行，在可执行文件后追加 `--ozone-platform=x11`，例如： - ``` + ```desktop Exec=/opt/SPlayer-Next/SPlayer-Next --ozone-platform=x11 %U ``` 4. 保存退出。 From e7888a3589f2da6660622b21a77bcdadfe80bc28 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Thu, 18 Jun 2026 21:57:01 +0800 Subject: [PATCH 11/13] =?UTF-8?q?docs:=20=E6=9B=B4=E6=94=B9=E4=B8=80?= =?UTF-8?q?=E4=BA=9B=E8=A1=A8=E8=BF=B0=EF=BC=8C=E5=A2=9E=E5=8A=A0=E4=BA=86?= =?UTF-8?q?=E5=A6=82=E4=BD=95=E5=88=A4=E6=96=AD=E7=AA=97=E5=8F=A3=E6=98=AF?= =?UTF-8?q?=E5=90=A6=E6=98=AF=E5=8E=9F=E7=94=9F=20Wayland?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/wayland.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/wayland.md b/docs/troubleshooting/wayland.md index be7f013..c54d69a 100644 --- a/docs/troubleshooting/wayland.md +++ b/docs/troubleshooting/wayland.md @@ -120,4 +120,16 @@ window-rule { ## 报障信息 -如遇问题，请在 Issue 中附上：发行版、桌面环境与合成器、是否启用了原生 Wayland，以及具体的窗口异常现象。 +如遇问题，请在 Issue 中附上：发行版、桌面环境与合成器、本程序是原生 Wayland 还是 Xwayland，以及具体的窗口异常现象。 + +> [!TIP] +> +> 要判断一个窗口是原生 Wayland 还是 Xwayland 主要有以下两种方式 +> +> - xprop +> +> 安装在终端中执行 `xprop`，然后点击对应的窗口。若什么事情都没发生，则该窗口是原生 Wayland；若终端中出现了该窗口的详细信息，则该窗口是 Xwayland +> +> - xeyes +> +> 安装并打开 `xeyes`，应该会打开一个窗口，上面有 “一双眼睛”。在 Xwayland 窗口中，它的视线会跟随鼠标（一直看向鼠标所在的位置）；在原生 Wayland 窗口中，它保持不动 From a62f4bef0c156f528d6368bd76c159b38f9a0647 Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Thu, 18 Jun 2026 22:07:16 +0800 Subject: [PATCH 12/13] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=20linux=20?= =?UTF-8?q?=E7=9A=84=E6=8F=90=E4=BA=A4=20issue?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/troubleshooting/debug.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/troubleshooting/debug.md b/docs/troubleshooting/debug.md index 9a3e61c..865419f 100644 --- a/docs/troubleshooting/debug.md +++ b/docs/troubleshooting/debug.md @@ -36,6 +36,10 @@ 请附上：操作系统与版本、SPlayer-Next 版本（开发版附 Commit ID）、Console 完整错误日志、可复现的操作步骤。 +> [!IMPORTANT] +> +> 如果是 Linux，请先查看 [Linux Wayland 兼容性](./wayland)。报告故障时附带桌面环境、发行版、所使用的安装包格式（官方包）或构建脚本（第三方包） + ## 重置应用 ::: warning 注意 From cca43daefbf39f14713a3aa85d9ddbb7ecfdac0d Mon Sep 17 00:00:00 2001 From: MoYingJi Date: Thu, 18 Jun 2026 22:35:46 +0800 Subject: [PATCH 13/13] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E8=B4=A1?= =?UTF-8?q?=E7=8C=AE=E6=8C=87=E5=8D=97=E4=B8=AD=E7=9A=84=E7=A4=BA=E4=BE=8B?= =?UTF-8?q?=E5=91=BD=E4=BB=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/contributing.md b/docs/contributing.md index 7108309..b31a000 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -20,12 +20,17 @@ pnpm install # 启动开发（先以 debug 构建原生模块，再启动 Electron） pnpm dev + +# 启动开发时向程序传递参数 +pnpm dev -- [参数]... ``` 只做界面开发、想跳过 Rust 编译时，可设置 `SKIP_NATIVE_BUILD=true`。 ## 构建 +基础命令 + ```bash pnpm build # 完整构建：清理 → 原生模块 → 类型检查 → electron-vite pnpm build:win # 打包 Windows @@ -33,6 +38,19 @@ pnpm build:mac # 打包 macOS pnpm build:linux # 打包 Linux ``` +高级命令 + +```bash +# 仅构建未打包的程序目录，常用于本地测试（在 dist/xxx-unpacked 目录） +pnpm build:unpack + +# 上面的构建命令默认会构建当前平台和架构的全部 target。可以通过下面的方法指定只打包某些 target +pnpm build:win nsis # 打包 Windows 的 nsis 格式 +pnpm build:mac dmg # 打包 macOS 的 dmg 格式 +pnpm build:linux tar.gz # 打包 Linux 的 tar.gz 格式 +# 全部 target 的列表详见 https://www.electron.build/docs/targets +``` + ## 常用脚本 ```bash