Typecho清爽BGM播放器+动态渐变CSS

给 Typecho 博客换一个「换页不断」的 BGM 播放器YoduPlayer 2.9.4 从安装到调色摘要很多 Typecho 音乐插件装上后都会遇到三个问题——换页就断、样式改不动、歌单一挂整站报错。YoduPlayer 在 2.6.5 的基础上重做了一遍玻璃拟态外观全后台可调、切页不中断、歌词竖向滚动、贴边自动隐藏接口也做了加固。这篇把安装、配置和踩过的坑一次讲完。关键词Typecho、Typecho 插件、博客 BGM、音乐播放器、PHP、前端本文目录一、先说结论旧插件到底难用在哪二、它长什么样三、核心能力一览四、安装三步五、后台配置速查六、几个值得单独说的细节七、常见问题八、版本与许可九、最后TL;DR如果你只关心三个点——换页不断PJAX 下音频对象不销毁整页刷新也有跨页续播兜底、外观后台可调主题模式、主副色、渐变、毛玻璃、圆角阴影全在设置页改不用碰 CSS、接口加固参数白名单、密钥与 HMAC 签名、缓存哈希化原子写入换域名换 https 旧缓存照样用那这篇可以直接跳到第四节安装。其余内容主要是配置速查表、几个实现细节的解释以及一份常见问题对照表遇到具体报错时再回来查即可。一、先说结论旧插件到底难用在哪给博客挂 BGM 这件事说简单也简单一个audio加几个按钮。但真正用起来痛点很集中常见问题具体表现换页就断点进文章、翻页、切分类音乐立刻停得重新点播放样式改不动想换个主色、调个透明度只能去翻player.css手改一升级全丢手机端难受播放器要么直接隐藏要么占掉半屏歌单一挂就白屏接口返回异常、PHP 报个 Warning整个列表直接空掉甚至 500和主题冲突主题的聚焦样式、层级把播放器顶掉我这次做的事情就是把这几个问题挨个解决同时把「外观」做成后台可调的参数而不是写死在 CSS 里。二、它长什么样播放器日常是这样右上角一个圆形按钮点开是玻璃拟态面板——封面、歌名、歌词、可拖动进度条、上一首/播放/下一首、播放模式、歌单、音量。四种模式分别是列表循环 / 随机播放 / 顺序播放 / 单曲循环图标是一套线性的回环箭头单曲循环中间带一个「1」。三、核心能力一览外观全部后台可调不用改代码设置项作用主题模式跟随系统 / 浅色 / 深色 / 完全自定义主色、副色渐变的两端同时驱动按钮、进度条、高亮渐变角度 流动速度0–360 度速度支持关闭色相循环强调色绕色环缓慢转动整块 UI 一直在变色面板底色 不透明度决定「玻璃」的通透程度毛玻璃模糊 / 圆角 / 阴影强度面板质感三件套文字颜色留空自动按底色取深浅色封面旋转速度播放时唱片转速手机端显示 布局隐藏 / 紧凑底部抽屉/ 完整贴边自动隐藏收成屏幕边缘的透明长方体把手点一下出面板播放体验进度条可拖动、音量条可拖键盘快捷键空格、←/→快进 5 秒、↑/↓音量、M静音、L列表、Esc收起系统媒体控制锁屏、通知栏、耳机线控可以显示歌名并切歌Media Session记住播放进度歌曲、秒数、音量存在 localStorage刷新接着放跨页续播整页刷新后自动接着上次的进度浏览器拦截自动播放时提示点一下PJAX / instantclick 不中断主题开启 PJAX 后换页只重挂 UI音频对象不销毁音乐连续。歌词有歌词时标题/歌手那块会变成歌词窗同时显示三行当前句高亮居中上下两行渐隐切换用requestAnimationFrame逐帧插值追赶目标位置是滑过去的不是一格一格跳自动过滤「作词/作曲/编曲」这类制作信息纯音乐自动隐藏。安全与兼容接口参数白名单type/server/id缓存文件名哈希化 原子写入playlist/song需要密钥url/pic/lrc走 HMAC 签名缓存里只存歌曲引用换域名、换 https 不用重新生成缓存兼容 Typecho 1.1 / 1.2PHP 7.2实测 8.3 正常。四、安装三步前提你已经有一个能正常访问的 Typecho 站点usr/plugins目录可写。第一步拿到插件包从仓库 GitHub - XES8/YoduPlayer: 一款清爽的 BGM 播放器支持 instantclick 页面切换不中断播放。 · GitHub 下载最新压缩包或 clone 后自行打包成 zip。解压后的目录名应为YoduPlayer。第二步放进插件目录把整个YoduPlayer目录放到你的网站根目录/usr/plugins/YoduPlayer/最终路径必须长这样/usr/plugins/YoduPlayer/Plugin.php两个常见错误解压后多套了一层变成YoduPlayer/YoduPlayer/Plugin.php—— 把内层文件提上来按压缩包名解压成YoduPlayer-2.9.4/—— 改名为YoduPlayer。目录名不能改插件的资源路径和/yoduapi路由都依赖它。第三步后台启用后台 → 控制台 → 插件 → 找到 YoduPlayer → 启用 → 进入「设置」按需配置。启用后前台按CtrlShiftR硬刷新一次静态资源带版本号但第一次换版本建议强制刷新。五、后台配置速查外观设置推荐值说明主题模式跟随系统自动适配访客的深色模式主色 / 副色#5b8cff/#ff6fa5蓝粉渐变和大多数主题都搭渐变角度135斜向右下流动速度9数字越大越慢填 0 静止面板不透明度7260–85 之间最像玻璃毛玻璃模糊14移动端建议不超过 16圆角 / 阴影18 / 60按主题气质微调手机端是否显示显示否则窄屏下整个播放器不显示手机端布局紧凑只留按钮点开才是底部抽屉贴边自动隐藏按需想要「藏在屏幕边上」就开歌单两种方式二选一歌单 id推荐网易云music.163.com/#/playlist?id7694448425→ 填7694448425QQ 音乐同理歌曲列表支持标准 JSON也兼容旧写法{title:歌名,artist:歌手,mp3:https://example.com/a.mp3,cover:https://example.com/a.jpg},注意网易云/QQ 音乐的接口受版权与风控影响个别歌单会返回「歌单涉嫌违规审核中」或者干脆取不到。这是平台侧限制不是插件坏了——播放器会把平台给的原话直接显示在列表里方便判断。六、几个值得单独说的细节1为什么换页音乐不断音频对象挂在页面级变量上主题用 PJAX/instantclick 换页时 DOM 会替换但 JS 上下文还在插件只重新绑定界面不碰audio。如果主题是整页刷新没开 PJAX就用「跨页续播」兜底记住秒数、新页面自动跳过去浏览器不让自动播放时提示点一下。2歌词为什么看起来顺滑不是 CSStransition而是requestAnimationFrame每帧把当前位置朝目标位置追 18% 的距离接近时自动收尾。CSS 过渡和逐帧位置更新同时存在会互相打架看着就一顿一顿。3贴边隐藏为什么单独做很多「贴边隐藏」是拿一个透明热区盖在屏幕边上会挡住页面右侧的点击。这里改成监听鼠标横坐标靠近右边缘才滑出不占任何点击区域。4接口为什么不怕换域名缓存文件里只存{歌名, 歌手, 源, 歌曲 id, 封面 id}签名地址在响应时按当前域名现算。所以换域名、加 https旧缓存照样能用。七、常见问题现象原因与处理装上没反应先CtrlShiftR再看后台插件是否已启用后台点启用报 500多为 PHP 版本或文件权限问题打开config.inc.php临时加define(__TYPECHO_DEBUG__, true);看具体报错提示「插件 YoduPlayer 的配置信息没有找到」插件在「已启用」里但配置没写入停用再启用一次即可歌单列表空列表里会显示平台返回的原因可用3778678网易云热歌榜验证插件链路是否正常手机上看不到检查「手机端是否显示」是否为「显示」换页音乐停一下主题未开 PJAX 时是整页刷新开启「跨页续播」或在主题里启用 PJAX目录被删后整站报class YoduPlayer_Plugin not found数据库还认为插件已启用。把usr/plugins/YoduPlayer/放回去即可以后先「停用」再删目录八、版本与许可当前版本2.9.4作者OsAtNb仓库GitHub - XES8/YoduPlayer: 一款清爽的 BGM 播放器支持 instantclick 页面切换不中断播放。 · GitHub协议BSD-3-Clause基于 jrotty/YoduPlayer 2.6.5 二次开发内置 Meting 为 MIT更新节奏上2.7.x 主要修兼容与安全Typecho 1.2 表单 API、PHP 8.2 弃用告警、缓存路径2.8.x 补了播放模式、贴边隐藏、跨页续播2.9.x 把播放模式图标和歌词滚动打磨了一轮。九、最后如果你只是想要一个「装上就能用、颜色能自己调、换页不吵」的博客 BGM这个插件应该够用如果你正在维护自己的 Typecho 主题也欢迎直接拿去改——代码是 BSD-3保留版权声明即可。安装或使用中遇到问题欢迎在仓库提 Issue附上Typecho 版本 PHP 版本 报错原文定位会快很多。如果这篇对你有帮助点个赞、收个藏就是对我最大的支持 layer titlejrotty/YoduPlayerjrotty/YoduPlayer 2.6.5 二次开发内置 Meting 为 MIT更新节奏上2.7.x 主要修兼容与安全Typecho 1.2 表单 API、PHP 8.2 弃用告警、缓存路径2.8.x 补了播放模式、贴边隐藏、跨页续播2.9.x 把播放模式图标和歌词滚动打磨了一轮。九、最后如果你只是想要一个「装上就能用、颜色能自己调、换页不吵」的博客 BGM这个插件应该够用如果你正在维护自己的 Typecho 主题也欢迎直接拿去改——代码是 BSD-3保留版权声明即可。安装或使用中遇到问题欢迎在仓库提 Issue附上Typecho 版本 PHP 版本 报错原文定位会快很多。如果这篇对你有帮助点个赞、收个藏就是对我最大的支持