音乐播放器

一款面向 XIUNOX（Xiuno BBS X）的帖子内音乐播放插件，支持网易云歌曲 ID、自定义音频链接、多曲播放列表、同步歌词及多套响应式皮肤。

• 插件目录：wajxy_music_player

• 当前版本：1.0.7

• 兼容版本：XIUNOX 1.1

• 插件作者：金小颖论坛

• 官方网站：[https://www.52jiny.com/)

应用简介

音乐播放器可将帖子正文中的音乐短码自动转换为完整的内嵌播放器。用户可以通过发帖编辑器工具栏插入网易云歌曲 ID，也可以填写自己的音频与封面地址。

播放器采用响应式设计，可自动适配电脑和手机页面，并提供播放、暂停、上一首、下一首、单曲循环、静音、音量调节、进度拖动、播放列表及同步歌词等功能。

插件不修改 XIUNOX 核心文件，不创建额外数据库表，设置数据通过 XIUNOX Setting 系统保存。

主要功能

网易云歌曲播放

输入网易云歌曲 ID 后，插件会读取歌曲名称、歌手、专辑、封面、音频地址及歌词，并生成帖子内播放器。

支持单首歌曲：

[music]517567145[/music]

支持多首歌曲组成播放列表：

[music]517567145,2020593612,5271858[/music]

兼容以下短码：

[netease]517567145[/netease]

[music=517567145]

自定义音频链接

播放单个音频地址：

[musicurl]https://example.com/music.mp3[/musicurl]

填写歌曲名称与歌手：

[musicurl]歌曲名称|歌手名称|https://example.com/music.mp3[/musicurl]

同时填写封面：

[musicurl]歌曲名称|歌手名称|https://example.com/music.mp3|https://example.com/cover.jpg[/musicurl]

编辑器快捷插入

插件通过 XIUNOX 的 editor_custom_btns_end.php Hook 向 AIEditor 工具栏添加音乐按钮。

点击按钮后可选择：

• 网易云歌曲 ID

• 自定义音频链接

填写完成后，插件会将安全编码后的音乐短码插入帖子，无需手动输入标签。

完整播放控制

帖子播放器支持：

• 播放与暂停

• 上一首与下一首

• 单曲循环

• 点击声音按钮静音或恢复声音

• 音量滑块调节

• 点击进度条跳转播放位置

• 当前播放时间与歌曲总时长

• 点击播放列表切换歌曲

• 当前歌曲高亮

同步歌词

对于包含时间标签的 LRC 歌词，播放器会根据歌曲进度自动同步：

• 中间显示当前歌词

• 当前歌词放大、加粗并使用皮肤强调色

• 上方显示上一句歌词

• 下方显示下一句歌词

• 拖动播放进度后自动重新定位歌词

• 歌词区域固定显示，不产生上下滚动条

响应式布局

播放器针对电脑和手机分别优化：

• 手机端控制按钮不会超出进度条左右边界

• 上一首、播放、下一首、循环、静音和音量控件自动缩放

• 手机端歌手位于左侧，来源位于右侧

• 超长歌曲名、歌手或来源自动省略，避免撑破布局

• 播放列表自动适配窄屏

播放器皮肤

插件内置五套皮肤：

黑金

经典深色专辑播放器风格，以金色作为主要强调色。

月光白

现代浅色玻璃质感，使用靛蓝强调色、柔和边框和半透明面板。

极光紫

紫、粉、青渐变组合，搭配深色毛玻璃控制区和粉紫描边按钮。

深海蓝

深蓝与青色渐变，采用青色进度条、歌词和播放控制高亮。

翡翠绿

深翡翠背景与薄荷绿强调色，适合自然、沉稳的论坛主题。

各皮肤会同步适配：

• 播放／暂停按钮

• 上一首与下一首图标

• 循环按钮状态

• 声音与静音按钮

• 音量滑块

• 播放进度条

• 当前歌词

• 当前播放歌曲

后台设置

后台设置页遵循 WAJXY 插件统一 UI 规范，包含 Hero、环境卡、Pills Tab、开关行、胶囊输入、粘性保存栏和版权栏。

基础设置

• 启用插件

• 显示编辑器按钮

• 移动端显示

• 显示歌词

• 允许尝试自动播放

浏览器可能根据自动播放策略阻止未经过用户操作的音频播放。

播放界面

• 选择播放器皮肤

• 设置自定义强调色

接口与缓存

• 网易云 API 地址

• 单个播放器最大歌曲数量

• API 缓存时间

• 网络请求超时时间

推荐 API 地址：

https://api.paugram.com/netease/

也可填写带测试 ID 的完整地址：

https://api.paugram.com/netease/?id=517567145

插件请求其他歌曲时会自动替换其中的 id 参数。

限制范围

• 配置允许使用播放器的版块 ID

• 配置帖子正文选择器

版块 ID 留空时，默认允许所有版块使用。

安装方法

1. 解压 wajxy_music_player_v1.0.7.zip。

2. 将内层目录 wajxy_music_player 上传至 XIUNOX 的 plugin/ 目录。

3. 登录 XIUNOX 后台。

4. 进入插件管理页面，安装并启用“音乐播放器”。

5. 打开插件设置页，确认网易云 API、皮肤和使用范围。

6. 清理 XIUNOX tmp/ 编译缓存。

7. 强制刷新浏览器，确保加载最新 JS 与 CSS。

正确目录结构：

plugin/
└── wajxy_music_player/
    ├── conf.json
    ├── icon.png
    ├── logo.png
    ├── install.php
    ├── uninstall.php
    ├── upgrade.php
    ├── setting.php
    ├── hook/
    ├── model/
    ├── route/
    ├── static/
    └── view/

升级方法

1. 备份当前插件目录与设置。

2. 使用新版本的 wajxy_music_player 目录覆盖旧目录。

3. 在后台执行插件升级。

4. 清理 tmp/ 编译缓存。

5. 强制刷新浏览器。

6. 确认页面加载的资源版本与 conf.json.version 一致。

当前版本应加载：

music-player.js?v=1.0.7
music-player.css?v=1.0.7

运行环境

• XIUNOX 1.1

• PHP 环境需支持 cURL，才能使用服务端网易云代理

• HTTPS 站点建议启用 OpenSSL

• 前端浏览器需支持原生 fetch、Promise、MutationObserver 与 HTML5 Audio

• 网易云播放地址是否可用取决于第三方 API 与音乐源状态

安全设计

• 后台 POST 设置使用 CsrfService::input() 与 CsrfService::check()。

• 前台歌曲接口校验 CSRF Token。

• 帖子与接口动态内容通过 textContent / createTextNode() 写入。

• 编辑器用户输入先通过 DOM 文本编码，再插入编辑器。

• 网易云服务端代理仅允许 HTTP/HTTPS 协议及 80/443 端口。

• 服务端拒绝私有地址、保留地址与无效 IP，降低 SSRF 风险。

• API 请求设置超时和响应长度限制。

• 歌曲信息使用 CacheHelper::remember() 缓存。

• 插件不存储用户密码、不修改用户登录流程。

• 插件不创建额外数据库表。

常见问题

帖子显示“音乐加载失败：没有可播放地址”

请依次检查：

1. 网易云歌曲 ID 是否有效。

2. 后台 API 地址是否正确。

3. PHP cURL 是否可用。

4. 服务器是否可以访问 API 域名。

5. 浏览器控制台是否有跨域或混合内容错误。

6. 是否已清理失败缓存及 XIUNOX tmp/ 缓存。

7. 页面是否加载当前版本的 JS 文件。

更新后样式没有变化

请清理 XIUNOX tmp/ 编译缓存并强制刷新浏览器。必要时清理 CDN、反向代理或浏览器缓存。

歌曲无法自动播放

现代浏览器通常会阻止未经用户操作的自动播放。用户点击播放按钮后即可正常播放。

没有同步歌词

只有 API 返回带时间标签的 LRC 歌词时才能按播放进度同步。自定义音频链接默认不包含歌词。

部分歌曲无法播放

可能原因包括：

• 歌曲已下架

• 音源地址过期

• 地区或版权限制

• 第三方 API 暂时不可用

• 浏览器拒绝不安全的音频地址

卸载说明

卸载插件会：

• 删除 wajxy_music_player 设置项

• 清理插件歌曲缓存

插件不创建数据库表，因此不会遗留插件业务表。帖子中已经保存的音乐短码会保留为普通文本；重新安装并启用插件后可以再次渲染。

版权信息

Copyright 2026 金小颖论坛 版权所有。