Fuwari 主题侧边栏 Meting 音乐播放器不显示、不渲染解决教程

前言

使用 Halo + Fuwari 主题搭建博客侧边音乐播放器时，经常遇到播放器模块存在代码、脚本正常，但页面侧边栏完全不显示音乐部件，无法加载歌单封面、歌词、播放容器的问题。本文记录本人亲身踩坑全过程与完整解决方案，方便后续博主避坑参考。

问题现象

1. 主题后台已配置音乐播放器部件，歌单 ID、平台参数填写无误

2. 播放器组件文件 MusicPlayer.astro 存在，前端 JS 脚本正常加载

3. 网页源码找不到音乐容器标签，侧边栏循环不渲染 music 模块

4. 页面只残留播放器脚本，无完整音乐卡片 DOM 结构

根因排查

1. 主题配置文件 sidebar.widgets 侧边栏部件列表，默认未包含 music 项

2. 仅配置 categories、tag 分类标签，系统不会自动渲染音乐小组件

3. Fuwari 原生 SideBar.astro 侧边循环逻辑存在兼容 bug，无法自动识别新增音乐部件

解决方法

1. 修改主题源码 src/components/widget/SideBar.astro

2. 补充侧边栏默认部件回退列表：categories、music、tag、html

3. 修复侧边栏循环挂载逻辑，强制识别 music 播放器分支

4. 重新执行 pnpm 打包构建，重新打包主题压缩包

5. 覆盖部署主题文件，重启 Halo 博客服务

6. 后台侧边栏部件勾选音乐播放器，保存配置生效

最终效果

侧边栏原生音乐卡片正常显示，歌单、封面、容器、播放按钮全部正常渲染，页面结构稳定无错乱。