二次开发 开源 ZMusic 单人版 for Fabric 1.21.11 / NeoForge 1.21.1｜支持网易云、酷狗、游戏内扫码登录、歌词显示 3.7.1

1. 支持版本

• Fabric 1.21.11
• NeoForge 1.21.1

2. 安装方式
把对应版本的成品 jar 放入客户端的 mods 目录。

对应文件：

• Fabric：zmusic-fabric-1.21.11-3.7.1.jar
• NeoForge：zmusic-neoforge-1.21.1-3.7.1.jar

注意：

• 这是客户端模组，安装在玩家客户端
• 单人模式可直接使用
• 不依赖服务端插件即可完成基础播放、搜索、登录

3. 首次使用前的准备
本版本依赖音乐 API 服务。

需要在配置中填写可用的网易云 / 酷狗 API 地址。
如果你使用的是作者或自建的 API，请保证接口可访问。

建议优先使用内网或稳定可达地址，避免公网回流、代理或证书问题影响扫码和搜索。

4. 主要功能

• 单人模式本地搜索歌曲
• 单人模式本地播放歌曲
• 游戏内扫码登录账号
• 网易云音乐支持
• 酷狗音乐支持
• 歌词显示
• v2 风格命令别名支持

5. 命令说明
主命令入口支持：

• /zmusic
• /zm
• /music

常用命令：

/zm help
显示帮助信息

/zm play <platform> <keyword>
按平台和关键词直接播放第一首匹配歌曲

/zm search <platform> <keyword>
搜索歌曲并返回结果

/zm music <platform> <keyword>
搜索歌曲并返回可点击结果，点击后可直接播放

/zm stop
停止播放

/zm login qr <platform>
打开游戏内二维码登录界面

6. 平台参数
当前常用平台参数：

网易云：

• netease
• 163
• wy

酷狗：

• kugou
• kg

示例：

/zm play netease 周杰伦<br>/zm play kugou 落<br>/zm search kugou 陈奕迅<br>/zm login qr kugou<br>/zm stop
7. 歌词显示

• 当前歌词会在游戏界面右上角显示
• 仅显示歌词文本，不显示厚重背景面板
• 更适合边玩边看，不会过度遮挡画面

8. 二维码登录
支持游戏内打开二维码界面进行扫码登录。

当前使用体验：

• 可以在游戏内直接弹出二维码
• 扫码后可完成账号登录
• 登录成功后即可继续搜索、播放对应平台歌曲

9. 适用场景

• 单人存档背景音乐
• 建筑、跑图、挂机时听歌
• 不想搭建完整服务端插件环境，只想客户端直接用
• 想基于现有版本继续开发本地歌单、本地播放队列或更完整歌词系统

10. 已知说明

• 本版本核心目标是“单人可用”
• 命令风格尽量向 ZMusic v2 靠拢，但不是完全一比一复刻全部服务端逻辑
• 部分功能在单人本地模式下与传统服务器插件模式的行为仍可能存在差异
• 第三方音乐接口的可用性、返回结构、登录策略可能会影响实际体验
• 不同平台的版权、登录、接口限制可能带来个别歌曲不可播放或不可获取歌词的情况