小枫音乐播放器（XFMusicPlayer）插件使用文档

Zsens Admin 社区功能插件：在社区前台嵌入 XF Music Player（小枫音乐播放器）浮动播放器，支持云端歌单接口与本地自定义歌单两种数据源。

• 插件标识：XFMusicPlayer
• 类型：功能插件（plugin），宿主：community
• 当前版本：1.0.0
• 作者：kuakeba.cn

目录

1. [功能特性](#1-功能特性)
2. [环境要求](#2-环境要求)
3. [安装与启用](#3-安装与启用)
4. [注入机制](#4-注入机制)
5. [配置说明](#5-配置说明)
6. [数据源模式详解](#6-数据源模式详解)
7. [自定义歌单 JSON 格式](#7-自定义歌单-json-格式)
8. [CDN 说明](#8-cdn-说明)
9. [升级与缓存](#9-升级与缓存)
10. [常见问题排查](#10-常见问题排查)
11. [卸载](#11-卸载)
12. [目录结构](#12-目录结构)
13. [更新日志](#13-更新日志)

1. 功能特性

• 零依赖嵌入：无需 npm / 构建工具，通过 CDN 异步加载 XF Music Player IIFE 产物（player.xfyun.club）。
• 两种数据源：支持官方云端歌单接口（mode=cloud）和本地自定义歌单 JSON（mode=local）。
• Web Component + Shadow DOM：播放器内部样式完全隔离，不污染社区 CSS。
• 浮动右下角：固定浮动在右下角，移动端自动避让底部安全区。
• 记忆播放：默认开启 rememberPlayback，刷新页面自动恢复上次播放位置与音量。
• 宿主钩子注入：通过 renderAssets() 钩子输出前端资源，自动挂到 community layout 末尾的 {:plugin_assets()}。
• PJAX 兼容：播放器只在首次页面加载时初始化一次，全局 flag 防重复实例化，PJAX 无刷新切换不影响播放状态。

2. 环境要求

3. 安装与启用

1. 将 XFMusicPlayer 文件夹上传/放置到站点 plugins/XFMusicPlayer/ 目录。
2. 进入后台「应用中心 → 插件管理」，找到「小枫音乐播放器」。
3. 点击「启用」。系统自动完成：

  - static/ 静态资源复制到 public/static/XFMusicPlayer/；

  - 前台模板合并缓存自动重建。

1. 配置在后台「应用中心 → 插件管理 → 小枫音乐播放器 → 配置」维护（宿主通用插件配置页）。

启用后前台右下角即出现浮动音乐播放器，默认从 XF 官方热歌榜 API 加载歌单。

4. 注入机制

插件不覆盖任何 community 模板，而是通过 renderAssets() 钩子注入前端资源：

// XFMusicPlayerPlugin.php 中
public function renderAssets(): string
{
    // 返回一段含 CSS link、播放器容器 div、CDN 脚本加载 + IIFE 初始化的 HTML
}

宿主 community layout 末尾调用 {:plugin_assets()}（底层走 HookService::renderFrontAssets()），会自动遍历所有已启用插件并拼接各自的 renderAssets() 返回值输出到页面末尾。

优势：

• 升级 community 插件不会被覆盖；
• 同一页面多个功能插件可以共存；
• 插件禁用后自动从页面移除，无残留。

5. 配置说明

全部配置项在后台「应用中心 → 插件管理 → 小枫音乐播放器 → 配置」维护，宿主通用配置页按表单渲染与保存。

5.1 开关与数据源

5.2 外观与行为

5.3 CDN

6. 数据源模式详解

6.1 cloud（云端接口）

播放器通过 XF 官方 API 拉取歌单，后台只需填一个接口 URL。官方热歌榜示例：

https://music.api.xfyun.club/api/v1/music/top?platform=qq&topId=26

其他 platform：qq / netease / kugou / migu。

6.2 local（本地歌单）

在配置表单中粘贴完整 JSON 数组（见下一节格式），适合固定歌单或自定义曲库场景。

7. 自定义歌单 JSON 格式

[
  {
    "id": "1",
    "title": "歌曲名称",
    "artist": "歌手",
    "album": "专辑",
    "cover": "https://example.com/cover.jpg",
    "src": "https://example.com/audio.mp3",
    "duration": 240,
    "lyricsUrl": "https://example.com/lrc.lrc"
  },
  {
    "id": "2",
    "title": "Another Song",
    "artist": "Some Artist",
    "cover": "https://example.com/cover2.jpg",
    "src": "https://example.com/audio2.mp3"
  }
]

每个对象 至少 要有 id、title、src 三个必填字段。可选字段：artist、album、cover、duration（秒）、lyricsUrl。

跨域注意：cover 和 src 如果是跨域资源，需确保目标服务器返回正确的 CORS 头，否则彩色歌词、音频可视化等跨域特性会自动降级。

8. CDN 说明

默认使用小枫官方 CDN（中国大陆推荐）：

https://player.xfyun.club/js/music-player/music-player.min.js

备用 CDN（自动降级，无需手动配置）：

https://cdn.jsdelivr.net/npm/xf-music-player@latest/music-player.min.js

如需私有化部署，把 music-player.min.js 放到 public/static/XFMusicPlayer/ 目录，然后 CDN 地址改为 /static/XFMusicPlayer/music-player.min.js。

9. 升级与缓存

• 静态资源缓存：theme.css 与 music-player.min.js 以版本号作为查询参数。升级插件后宿主会自动 PluginService::copyStaticAssets('XFMusicPlayer') 覆盖。
• PHP OPcache：修改 XFMusicPlayerPlugin.php 后重启 php-cgi / PHP-FPM。
• renderAssets() $done 静态变量：同一请求生命周期内只输出一次；刷新页面或 PJAX 结束后恢复正常。

10. 常见问题排查

Q1：启用后前台没有播放器？

1. 检查后台配置「启用音乐播放器」开关；
2. 浏览器控制台查 [XFMusicPlayer] 前缀日志；
3. 确认 public/static/XFMusicPlayer/theme.css 存在，不存在则对插件点一次「升级」；
4. 确认服务器网络可访问 player.xfyun.club。

Q2：播放器显示但点击没反应？

浏览器自动播放策略拦截——保持「自动播放」关闭，用户手动点击即可。

Q3：控制台 CORS 错误？

XF 官方 API 已配置 CORS。自定义 api_url 需接口服务器返回 Access-Control-Allow-Origin: *。

Q4：local 模式歌单不显示？

JSON 格式校验（任意 JSON 校验网站）。每个对象至少要有 id、title、src。

Q5：PJAX 后被重建？

不会。全局 flag window._XFMUSICPLAYERINSTALLED__ 确保初始化只执行一次；renderAssets() 也有 PHP 侧静态变量防重复输出。

Q6：音频可视化 / 彩色歌词不生效？

跨域音频无法分析（浏览器安全限制）。音频放同域名或配 CORS。

11. 卸载

1. 后台「应用中心 → 插件管理」停用「小枫音乐播放器」。
2. 卸载时自动删除 public/static/XFMusicPlayer/ 静态资源。
3. plugins/XFMusicPlayer/ 源目录保留，可随时重新启用。

12. 目录结构

plugins/XFMusicPlayer/
├── plugin.json                # 插件元信息（标识/版本/入口类）
├── XFMusicPlayerPlugin.php    # 后端主类：配置表单 + renderAssets() 注入
├── static/
│   └── theme.css              # 播放器容器定位样式（浮动右下角 + 移动端适配）
├── icon.svg                   # 插件图标
├── README.md                  # 本文档
└── 使用说明.md                # 简明快速上手手册

13. 更新日志

1.0.0（2026-10-22）

• 首个版本。
• 基于 Zsens Admin community 插件架构（plugins/ 目录，非 themes/）。
• 通过 renderAssets() 钩子注入前端资源，宿主 {:plugin_assets()} 自动拼接。
• 异步加载官方 CDN（player.xfyun.club），失败自动降级 jsDelivr。
• 支持 cloud 云端歌单 / local 本地 JSON 两种数据源。
• 完整后台配置表单（20 项）。
• PJAX 兼容：全局 flag 防重复实例化 + PHP 静态变量防重复输出。
• Shadow DOM 样式隔离。
• 作者统一 kuakeba.cn。