接入文档

小枫

小枫音乐播放器接入文档

小枫音乐播放器是一款稳定、便捷、高性能的 HTML5 音乐播放器插件，面向生产环境分发。源码不对外开放时，只需要发布打包后的 npm 包和 CDN 文件，业务项目通过播放器标签自动挂载，或通过 JavaScript、Vue、React 实例化接入。

代码下载地址

GitHub Gitee

npm 安装命令

bash

npm install xf-music-player

发布文件

txt

dist/
  music-player.min.js
  music-player.esm.js
  old-music-player.min.js
  plugin/
    ie-out/
      index.js
    sakura/
      sakura.min.js

music-player.min.js：供 <script> 或 CDN 使用的固定名称 IIFE 产物。
music-player.esm.js：供 Vite、Webpack、Rollup 等现代构建工具使用的 ESM 产物。
old-music-player.min.js：旧版播放器兼容产物。
plugin/：可选的浏览器兼容检测和樱花特效插件。

安装

bash

pnpm add xf-music-player

也可以使用 npm 或 yarn：

bash

npm install xf-music-player
yarn add xf-music-player

快速使用

方式一：标签自动挂载

适合静态页面、博客、官网、活动页等无需复杂运行时配置的场景。

html

<script src="https://player.xfyun.club/js/music-player/music-player.min.js"></script>

<xf-music-player
  language="zh"
  theme="xf-original-theme"
  mode="cloud"
  api-url="https://music.api.xfyun.club/api/v1/music/top?platform=qq&topId=26"
  environment="production"
  remember-playback="true"
  play-mode="order"
  volume="0.8"
/>

标签方式只能传递字符串、数字、布尔值这类基础属性。playlist、audioProvider、生命周期钩子等复杂配置请使用 JS 实例化。

方式二：IIFE JS 实例化

适合不使用构建工具，但需要传入歌单、远程接口或后续调用实例 API 的页面。

html

<div id="player-root"></div>
<script src="https://player.xfyun.club/js/music-player/music-player.min.js"></script>
<script>
  const player = new window.XfMusicPlayer.MusicPlayer({
    tagName: 'xf-site-player',
    language: 'zh',
    isMonitoring: false,
    mountElement: document.querySelector('#player-root'),
    attributes: {
      theme: 'xf-original-theme',
      mode: 'local',
      environment: 'production',
      playerWidth: '324px',
      bottom: '24px',
      songListHeight: '350px',
      visibleSongListCount: 4,
      rememberPlayback: true,
      memoryKey: 'xf-site-player-memory',
      autoplay: false,
      playMode: 'order',
      volume: 0.8,
      isAutoPopup: false,
      isAutoPlaylist: false,
      colorfulLyric: false,
      playlist: [
        {
          id: 'demo-1',
          title: 'Demo Song',
          artist: 'Xiao Feng',
          cover: 'https://player.xfyun.club/img/half.jpg',
          src: 'https://player.xfyun.club/mp3/half.mp3'
        }
      ]
    }
  })

  player.play()
</script>

IIFE 产物会暴露 window.XfMusicPlayer.MusicPlayer。

方式三：ESM / npm 引入

适合 Vue、React、Svelte、原生 Vite 等构建型项目。

ts

import { MusicPlayer } from 'xf-music-player'

const player = new MusicPlayer({
  tagName: 'xf-app-player',
  language: 'zh',
  isMonitoring: false,
  attributes: {
    theme: 'xf-original-theme',
    mode: 'cloud',
    apiUrl: '/api/v1/music/list?platform=qq',
    environment: 'production',
    rememberPlayback: true,
    memoryKey: 'xf-player-memory',
    playMode: 'order',
    volume: 0.8,
    isAutoPopup: true,
    isAutoPlaylist: false,
    isAutoPopup: true
  }
})

React 组件示例：

tsx

import { useEffect, useRef } from 'react'
import { MusicPlayer } from 'xf-music-player'

export default function MusicPlayerWidget() {
  const rootRef = useRef<HTMLDivElement | null>(null)

  useEffect(() => {
    const player = new MusicPlayer({
    tagName: 'xf-react-player',
      mountElement: rootRef.current || document.body,
      language: 'zh',
      isMonitoring: false,
      attributes: {
        theme: 'xf-original-theme',
        mode: 'local',
        environment: 'production',
        rememberPlayback: true,
        memoryKey: 'xf-react-player-memory',
        playMode: 'order',
        volume: 0.8,
        playlist: []
      }
    })

    return () => {
      player.destroy()
    }
  }, [])

  return <div ref={rootRef} className="music-player-root" />
}

如果你的 CDN 支持 ESM，也可以直接从 CDN URL 导入：

ts

import { MusicPlayer } from 'https://cdn.jsdelivr.net/npm/xf-music-player@latest/music-player.esm.js'

CDN 地址

中国大陆推荐使用小枫音乐播放器静态 CDN；jsDelivr 和 unpkg 可作为 npm CDN 备用线路：

html

<!-- 中国大陆推荐 -->
<script src="https://player.xfyun.club/js/music-player/music-player.min.js"></script>

html

<!-- jsDelivr IIFE -->
<script src="https://cdn.jsdelivr.net/npm/xf-music-player@latest/music-player.min.js"></script>

html

<!-- unpkg IIFE -->
<script src="https://unpkg.com/xf-music-player@latest/music-player.min.js"></script>

ts

// jsDelivr ESM
import { MusicPlayer } from 'https://cdn.jsdelivr.net/npm/xf-music-player@latest/music-player.esm.js'

小枫静态 CDN 的固定地址指向当前稳定版。官网示例使用 jsDelivr 的 @latest 标签；生产项目如需严格锁定构建结果，可将其替换为明确版本号（例如 @1.0.3）。

创建选项

ts

interface CreateMusicPlayerTagOptions {
  /** 自定义元素标签名，必须包含连字符；非法值会回退为 xf-music-player */
  tagName?: string
  /** UI 语言 */
  language?: 'zh' | 'en'
  /** 是否开启右侧系统监控面板，建议仅开发环境开启 */
  isMonitoring?: boolean
  /** 播放器运行配置，复杂对象和函数都从这里传入 */
  attributes?: MusicPlayerAttributes
  /** 挂载容器，默认 document.body */
  mountElement?: HTMLElement
  /** 是否关闭自动挂载，由业务主动调用 mount() */
  manualMount?: boolean
  /** 生命周期钩子，也可以通过链式 API 后续注册 */
  hooks?: MusicPlayerHooks
}

国际化语言

播放器当前支持 zh 和 en 两种语言。语言配置不属于 MusicPlayerAttributes，而是播放器实例或播放器标签的顶层配置。

标签方式：

html

<xf-music-player language="en"/>

JS / Vue / React 实例化方式：

ts

const player = new MusicPlayer({
  tagName: 'xf-music-player',
  language: 'en',
  attributes: {
    theme: 'xf-original-theme',
    playlist: []
  }
})

如果生产环境需要在中英文之间切换，建议销毁当前实例后用新的 language 重新创建播放器，确保错误提示音、按钮文案、歌词占位和提示信息全部同步到目标语言。

ts

await player.destroy()

const nextPlayer = new MusicPlayer({
  tagName: 'xf-music-player',
  language: 'zh',
  attributes: {
    theme: 'xf-original-theme',
    playlist
  }
})

在线调试页的语言选择会同步影响预览播放器，并在 HTML、JavaScript、Vue、React 配置代码中自动生成对应配置。

手动挂载示例：

ts

const player = new MusicPlayer({
  manualMount: true,
  mountElement: document.querySelector('#player-root') as HTMLElement,
  attributes: {
    rememberPlayback: true,
    playMode: 'single'
  }
})

player
  .beforeRender(el => console.log('before render', el))
  .afterRender(el => console.log('after render', el))
  .mount()

歌曲数据格式

ts

interface SongInfo {
  id: string | number
  title: string
  artist?: string
  album?: string
  cover?: string
  /** 音频地址；云端数据允许为空，播放时会进入错误提示音兜底流程 */
  src?: string | null
  duration?: number
  lyrics?: string | ILyricItem[]
  lyricsUrl?: string | null
}

lyrics 支持结构化数组或标准 LRC 字符串；lyricsUrl / lyrics_url 可指向外链 LRC 文本。切歌时播放器会取消旧歌词请求，只应用当前歌曲的歌词结果。

txt

[00:00.00] Song title
[00:05.00] First lyric line

配置项

以下配置对应 MusicPlayerAttributes，通过 JS / Vue / React 实例化时放入 attributes，通过标签方式接入时使用短横线属性名，例如 rememberPlayback 对应 remember-playback。

字段	类型	默认值	说明
`theme`	`string`	`xf-original-theme`	内置主题名，也支持 `random-theme`、`auto-theme`
`customThemeName`	`string`	-	从页面样式表提取同名 class/id CSS 变量
`customThemeStyle`	`string`	-	注入自定义主题 CSS
`playerWidth`	`string`	`324px`	播放器宽度
`fontName`	`string`	-	字体名
`bottom`	`string`	`2em`	底部距离
`songListHeight`	`string`	`350px`	歌单展开高度
`visibleSongListCount`	`number`	`4`	歌单可视歌曲数量
`isAutoPopup`	`boolean`	`false`	是否自动弹出/展开播放器，只控制界面状态，不触发播放
`isAutoPlaylist`	`boolean`	`false`	是否展开歌单
`colorfulLyric`	`boolean`	`false`	是否启用彩色歌词和封面取色背景
`audioVisualizer`	`boolean`	`false`	是否启用 2D Canvas 实时音频可视化；开启后进度条使用连续波形展示播放进度，底部歌词条同步显示底部对齐的柱状音频背景；多彩歌词开启时每个柱状线使用稳定分色，跨域音频无法分析时会自动降级
`lazyLoadTimer`	`number`	`0`	延迟初始化播放器的时间，单位 ms
`lazyLoadAnimationUrl`	`string`	按主题自动选择	主封面和歌单封面加载前展示的动画图
`mode`	`cloud \| local`	`cloud`	数据源模式；云端模式使用 `apiUrl`，本地模式使用 `playlist` / `audioProvider`
`apiUrl`	`string`	`VITE_API_URL`	云端歌单接口地址，也可通过 `api-url` 属性自定义；支持 `{environment}` 占位符
`environment`	`development \| production \| test`	`production`	当前环境
`rememberPlayback`	`boolean`	`true`	是否记忆播放
`memoryKey`	`string`	`xf-music-player-memory`	localStorage 记忆 key
`autoplay`	`boolean`	`false`	是否挂载后尝试自动播放，只控制播放启动，不控制播放器弹出
`playMode`	`order \| single \| random`	`order`	播放模式
`volume`	`number`	`0.8`	音量，范围 0-1
`playlist`	`SongInfo[]`	`[]`	本地初始歌单；构建产物不内置 mock 数据
`audioProvider`	`MusicAudioProvider`	-	自定义音频接口

标签方式只适合字符串、数字、布尔值等基础属性；playlist、audioProvider、生命周期钩子和复杂对象请使用 JS / Vue / React 实例化。

TypeScript 配置类型：

ts

type MusicPlayerAttributes = {
  theme?: string
  customThemeName?: string
  customThemeStyle?: string
  playerWidth?: string
  fontName?: string
  bottom?: string
  songListHeight?: string
  visibleSongListCount?: number
  isAutoPopup?: boolean
  isAutoPlaylist?: boolean
  colorfulLyric?: boolean
  audioVisualizer?: boolean
  lazyLoadTimer?: number
  lazyLoadAnimationUrl?: string
  mode?: 'cloud' | 'local'
  apiUrl?: string
  environment?: 'development' | 'production' | 'test'
  rememberPlayback?: boolean
  memoryKey?: string
  autoplay?: boolean
  playMode?: 'order' | 'single' | 'random'
  volume?: number
  playlist?: SongInfo[]
  audioProvider?: MusicAudioProvider
}

播放器内部状态包含标签名、监控状态、语言、播放器配置、播放运行态和播放控制命令。业务侧通常不需要直接访问内部 Store，生产环境优先使用 MusicPlayer 实例 API；在线调试控制台会基于这些状态能力做可视化配置。

ts

type MusicStoreState = {
  tagName: string
  isMonitoring: boolean
  language: 'zh' | 'en'
  playerConfig: MusicPlayerAttributes
  playback: MusicPlaybackState
  command: MusicPlayerCommand | null
  setTagName: (val?: string) => void
  toggleMonitoring: (val?: boolean) => void
  setLanguage: (val: 'zh' | 'en') => void
  updatePlayerConfig: (config: Partial<MusicPlayerAttributes>) => void
  setPlaylist: (playlist: SongInfo[], currentIndex?: number) => void
  updatePlayback: (state: Partial<MusicPlaybackState>) => void
  setPlayMode: (mode: 'order' | 'single' | 'random') => void
  dispatchCommand: (type: MusicPlayerCommandType, payload?: unknown) => void
  clearMusicPlayerInstance: () => void
}

播放器插槽

播放器是 Web Component，可以在 <xf-music-player> 内部传入命名插槽和默认插槽，方便业务方扩展自定义按钮、提示、品牌内容或歌词控制区域。插槽内容仍保留在页面 Light DOM 中，业务样式可以直接作用于这些节点。

html

<xf-music-player
  theme="xf-original-theme"
  is-auto-popup="true"
  language="zh"
  player-width="350px"
  bottom="3em"
  font-name="Google Sans Code"
  is-monitoring="false"
  colorful-lyric="false"
>
  <div slot="player-default">播放器默认插槽</div>
  <div slot="player-content">播放器内容插槽</div>
  <div slot="player-lyrics">歌词控制插槽</div>
  <div>默认插槽</div>
</xf-music-player>

插槽名	说明
`player-default`	注入播放器默认控制区域的扩展内容，适合放置轻量按钮或提示
`player-content`	注入播放器主体内容区域，适合展示业务自定义内容
`player-lyrics`	注入歌词控制区域，适合扩展歌词相关开关或状态
默认插槽	未声明 `slot` 的节点会作为宿主默认内容输出

云端模式

mode 默认是 cloud。未显式配置 apiUrl 时，播放器会读取构建时的 VITE_API_URL：

官网项目使用 server/.env 中的 API_URL 生成播放器接口示例和在线调试默认地址；SITE_URL 只用于网站域名、静态资源、SEO、RSS 与站点地图，两者可以配置为不同域名。

txt

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

也可以通过标签或 JS 配置覆盖：

html

<xf-music-player
  mode="cloud"
  api-url="https://music.api.xfyun.club/api/v1/music/top?platform=qq&topId=26"
/>

ts

new MusicPlayer({
  attributes: {
    mode: 'cloud',
    apiUrl: '/api/v1/music/list?platform=qq'
  }
})

云端模式下，如果配置了有效 apiUrl，播放器会先请求云端歌单，成功后再渲染播放器主体和歌词。接口超过 1.5 秒仍未响应时，会弹出国际化提示：云端歌曲正在拉取中请稍后；接口超过 10 秒、返回失败或返回空歌单时，会弹出 播放器云端数据加载失败。

云端歌单接口需要返回统一结构：

json

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "002qU5aY3Qu24y",
      "title": "青花瓷",
      "artist": "周杰伦",
      "album": "我很忙",
      "cover": "https://y.qq.com/music/photo_new/T002R300x300M000002eFUFm2XYZ7z.jpg",
      "src": null,
      "duration": 239,
      "lyrics_url": "https://music.api.xfyun.club/api/v1/music/lyric?platform=qq&songId=002qU5aY3Qu24y"
    }
  ]
}

失败结构：

json

{
  "code": 500,
  "msg": "服务器错误",
  "data": null
}

当 code !== 200 时，播放器会读取 msg 作为错误信息。src 可以为空；用户播放这类歌曲时，播放器不会创建空音频实例，而是播放当前语言的错误提示音，提示音结束后切换下一首。连续 3 首失败后停止播放。

如果 apiUrl 中包含 {environment}，播放器会自动替换为当前 environment：

ts

new MusicPlayer({
  attributes: {
    mode: 'cloud',
    apiUrl: '/api/{environment}/music/list',
    environment: 'production'
  }
})

歌词接口支持普通 LRC 文本，也支持统一 JSON 响应。播放器只读取 data.lyric：

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "lyric": "[00:00.00] 第一行歌词"
  }
}

XF API Server 接入示例

官网调试页提供 XF API 地址生成器，可根据服务地址、平台和接口参数自动生成 api-url，并支持拉取预览。推荐直接用于播放器云端模式的接口：

以下生产示例的接口域名来自 server/.env 中的 API_URL，与网站域名 SITE_URL 独立配置。

GET https://music.api.xfyun.club/api/v1/music/top?platform=netease&topId=3778678GET https://music.api.xfyun.club/api/v1/music/top?platform=qq&topId=26GET https://music.api.xfyun.club/api/v1/music/playlist-songs?platform=netease&playlistId=3778678GET https://music.api.xfyun.club/api/v1/music/playlist-songs?platform=qq&playlistId=8523075134

歌曲数据中的 lyrics_url 会在播放或切歌时请求，播放器只读取歌词接口响应中的 data.lyric：

GET https://music.api.xfyun.club/api/v1/music/lyric?platform=netease&songId=5257138GET https://music.api.xfyun.club/api/v1/music/lyric?platform=qq&songId=002qU5aY3Qu24y

top、playlist-songs 的 data 直接是播放器歌曲数组。search 只返回歌曲基础信息，不包含 src、duration、lyrics_url，不作为调试器的 api-url 生成入口，避免把不可播放的基础歌曲信息写入播放器。

本地模式

mode="local" 不会主动请求 apiUrl，适合离线页面、静态歌单或业务自己控制数据源：

ts

new MusicPlayer({
  attributes: {
    mode: 'local',
    playlist: [
      {
        id: 'local-1',
        title: 'Local Song',
        src: '/audio/demo.mp3'
      }
    ]
  }
})

自定义音频接口

ts

type MusicSongListPayload = SongInfo[] | { list: SongInfo[] } | { playlist: SongInfo[] } | { songs: SongInfo[] }

interface MusicApiResponse<T> {
  code: number
  msg?: string
  data: T | null
}

type MusicAudioProvider = (
  context: MusicAudioProviderContext
) => Promise<MusicSongListPayload | MusicApiResponse<MusicSongListPayload>> | MusicSongListPayload | MusicApiResponse<MusicSongListPayload>

interface MusicAudioProviderContext {
  environment: 'development' | 'production' | 'test'
  playerConfig: MusicPlayerAttributes
  signal?: AbortSignal
}

audioProvider 优先级高于内置 mode/apiUrl 逻辑，适合业务需要自行签名、鉴权或组合多接口的场景。它支持直接返回 SongInfo[]、{ list: SongInfo[] }，也兼容 { code: 200, msg: 'success', data: SongInfo[] }。播放器会自动过滤危险协议和非法数据；当环境快速切换或组件销毁时，旧请求会被 AbortSignal 取消并且不会覆盖新歌单。

播放交互

音量图标点击后只展开或收起音量滑块，静音能力保留给公开 API、调试控制台或业务自定义入口。
音量面板支持拖动调节，并实时显示 0% 到 100%。
主封面切歌时会先渲染主题加载图，并保留约 120ms 最小展示时间。
进度条支持拖动；拖动开始时会暂停正在播放的音频，松手后 seek 到目标位置并自动播放。
上一首、下一首、歌单开关和播放模式按钮带前沿防抖。
点击当前歌单歌曲会播放或暂停，点击其他歌曲会切换并播放。
歌单图片使用懒加载策略，进入视口并停留 150ms 后替换真实图片。
播放、暂停、切歌、歌单开关、静音和切换播放模式都会触发居中提示。
歌词遵循播放生命周期：播放时显示，暂停或停止时隐藏。
点击底部歌词条会打开全屏歌词弹窗，点击歌词行会跳转到对应播放时间。

键盘控制

按键	行为
`Tab`	切换播放器收缩/展开状态，即 `isAutoPopup`
`Space`	播放或暂停当前歌曲
`ArrowLeft`	上一首
`ArrowRight`	下一首

键盘控制会跳过输入框、下拉框、按钮、滑块、contenteditable 和组合输入状态；同时会忽略 Ctrl、Meta、Alt 组合键，避免抢占系统或浏览器原生快捷键。

失败兜底

音频加载或播放失败时，播放器不会直接卡死在当前歌曲，而是按当前语言播放内置错误提示音。错误提示音播放完成后会自动切换下一首；连续 3 首歌曲播放失败时停止自动播放，并通过错误提示告知用户。

记忆播放

rememberPlayback 默认开启；业务显式传入 rememberPlayback: false 或 remember-playback="false" 后会关闭。开启时播放器会在 memoryKey 下保存结构化记忆：

ts

interface MusicMemoryState {
  current: MusicMemoryRecord | null
}

current 保存当前歌曲的记忆，包括歌曲 id、音频地址、进度、音量、静音状态、播放模式和歌词手动隐藏偏好。

实例 API

ts

player.play()
player.pause()
player.toggle()
player.stop()
player.prev()
player.next()
player.select(0)
player.seek(30)
player.setVolume(0.6)
player.mute(true)
player.setPlayMode('single')
player.setPlaylist(list, 0)
player.setConfig({
  theme: 'xf-dark-theme',
  songListHeight: '350px',
  visibleSongListCount: 4,
  lazyLoadAnimationUrl: '/imgs/custom-loader.svg'
})
player.destroy()

生命周期

播放器生命周期分为外层 MusicPlayer 控制器和内部 Web Component 生命周期。接入方只需要使用公开钩子，不需要直接操作内部组件。

触发顺序

new MusicPlayer(options)：归一化配置、注册自定义元素、创建宿主 DOM。
mount()：宿主 DOM 插入页面；自动挂载模式下该步骤会在构造后的微任务执行。
beforeRender(el)：宿主元素连接到页面后触发。
内部初始化：写入运行配置、解析主题、加载歌单、恢复记忆播放。
afterRender(el)：宿主元素首次渲染完成后触发。
beforeUpdate(el, changed)：响应式属性或状态联动触发 DOM 更新前执行。
afterUpdate(el, changed)：DOM 更新完成后执行。
destroy() 或 DOM 移除：触发 beforeDestroy(el)，随后清理计时器、订阅、音频实例、页面监听和临时资源。
afterDestroy()：内部清理完成后触发。

钩子注册

ts

player
  .beforeRender(el => {})
  .afterRender(el => {})
  .beforeUpdate((el, changed) => {})
  .afterUpdate((el, changed) => {})
  .beforeDestroy(el => {})
  .afterDestroy(() => {})

销毁示例：

ts

await player.destroy({
  timer: 300,
  beforeDestroy: async el => {
    // 一次性销毁前回调。
  },
  afterDestroy: () => {
    // 一次性销毁后回调。
  }
})

自定义主题

通过 CSS 变量覆盖播放器主题：

css

.my-player-theme {
  --background-color: #fbfffd;
  --theme-color: #1e7d58;
  --text-color: #7d9e92;
  --song-name-color: #4d9678;
  --text-deputy-color: #6a8e80;
  --text-hover-color: #26996c;
  --text-hover-color-rgb: 38, 153, 108;
}

ts

player.setConfig({ customThemeName: 'my-player-theme' })

技术栈与优势

播放器核心基于 Lit + Howler + TypeScript 开发。Lit 负责 Web Component、响应式属性、Shadow DOM 渲染和生命周期；Howler 统一处理播放、暂停、进度、音量、切歌与音频资源释放。

响应式稳定：配置、歌单、歌词、主题和播放状态自动驱动界面更新。
跨框架复用：HTML、Vue、React、Svelte、Angular 与静态页面共享同一套标签和实例 API。
音频生命周期可靠：统一回收音频实例、监听器、请求和计时器，降低多实例资源泄漏风险。
性能可控：延迟初始化、封面懒加载、请求取消、状态节流与歌词滚动集中管理。
生产可维护：公开配置、数据结构、生命周期和错误兜底保持清晰边界。

浏览器兼容性

推荐使用现代 Chrome、Edge Chromium、Firefox、Safari 以及主流移动端现代浏览器。播放器依赖 customElements、HTMLElement、Shadow DOM、Promise、Symbol、Object.assign、JavaScript 和 HTML5 Audio。

以下环境不支持或不建议用于生产：

Internet Explorer 全部版本：明确不支持，可使用兼容检测插件引导升级。
旧版 Edge Legacy：不建议支持 EdgeHTML 内核版本。
Android 旧 WebView / 旧 UC / 旧 QQ 浏览器：缺少 Web Components 或基础 ES 能力时无法运行。
iOS 10 及以下 Safari：Web Components、Shadow DOM 与音频策略支持不稳定。
禁用 JavaScript、限制 Web Components 或不支持 HTML5 Audio 的环境：播放器无法初始化或播放。

浏览器插件

兼容检测插件放在播放器主包之前。检测到 IE、Edge Legacy 或关键能力缺失时，会跳转到浏览器升级页：

html

<script src="/player/plugin/ie-out/index.js"></script>
<script src="/player/music-player.min.js"></script>

樱花特效插件可独立使用，与播放器同页时建议放在主包之后：

html

<script src="/player/music-player.min.js"></script>
<script src="/player/plugin/sakura/sakura.min.js"></script>

CDN 地址：

html

<script src="https://cdn.jsdelivr.net/npm/xf-music-player@latest/plugin/ie-out/index.js"></script>
<script src="https://cdn.jsdelivr.net/npm/xf-music-player@latest/plugin/sakura/sakura.min.js"></script>

旧版迁移

新项目推荐使用 music-player.min.js 或 npm 包中的 MusicPlayer 实例 API。旧项目可暂时引入兼容产物：

html

<script src="/player/old-music-player.min.js"></script>

新页面使用 <xf-music-player> 或 new MusicPlayer(...)。
旧页面短期保留 old-music-player.min.js，逐步迁移配置、歌单和生命周期。
需要完整旧版代码与示例时，查看发布目录中的 xf-MusicPlayer-master/。

生产环境建议

CDN 引入时锁定明确版本号，不使用不带版本的 latest 地址。
复杂数据通过 JS 实例化传入，不建议塞进 HTML 属性。
生产环境关闭 isMonitoring。
如果页面中有多个播放器实例，自定义 tagName 必须包含连字符，并避免重复。
重新初始化播放器前先调用 destroy()，避免重复挂载和音频实例残留。
对远程歌曲、封面、歌词资源配置稳定的 HTTPS 地址。

FAQ

标签引入和 JS 引入怎么选？

静态页面、配置简单时用标签自动挂载；需要动态歌单、远程接口、生命周期钩子或实例 API 时用 JS 实例化。

CDN 和 npm 能同时提供吗？

可以。npm 包用于构建型项目，CDN 地址用于静态页面或低成本接入。两者建议指向同一个版本的打包产物。

源码不公开会影响使用吗？

不会。接入方只需要 npm 包或 CDN 文件，以及本文档里的配置项、数据结构和实例 API。

小枫音乐播放器接入文档 ​

代码下载地址 ​

npm 安装命令 ​

发布文件 ​

安装 ​

快速使用 ​

方式一：标签自动挂载 ​

方式二：IIFE JS 实例化 ​

方式三：ESM / npm 引入 ​

CDN 地址 ​

创建选项 ​

国际化语言 ​

歌曲数据格式 ​

配置项 ​

播放器插槽 ​

云端模式 ​

XF API Server 接入示例 ​

本地模式 ​

自定义音频接口 ​

播放交互 ​

键盘控制 ​

失败兜底 ​

记忆播放 ​

实例 API ​

生命周期 ​

触发顺序 ​

钩子注册 ​

自定义主题 ​

技术栈与优势 ​

浏览器兼容性 ​

浏览器插件 ​

旧版迁移 ​

生产环境建议 ​

FAQ ​

标签引入和 JS 引入怎么选？ ​

CDN 和 npm 能同时提供吗？ ​

源码不公开会影响使用吗？ ​

小枫音乐播放器接入文档

代码下载地址

npm 安装命令

发布文件

安装

快速使用

方式一：标签自动挂载

方式二：IIFE JS 实例化

方式三：ESM / npm 引入

CDN 地址

创建选项

国际化语言

歌曲数据格式

配置项

播放器插槽

云端模式

XF API Server 接入示例

本地模式

自定义音频接口

播放交互

键盘控制

失败兜底

记忆播放

实例 API

生命周期

触发顺序

钩子注册

自定义主题

技术栈与优势

浏览器兼容性

浏览器插件

旧版迁移

生产环境建议

FAQ

标签引入和 JS 引入怎么选？

CDN 和 npm 能同时提供吗？

源码不公开会影响使用吗？