Mahiro-Blog 新手教程（九）：音乐播放器与歌单配置实战

音乐模块是 Mahiro-Blog 的特色功能之一。新手最常见的诉求是：先让它正常播，再考虑 UI 微调。

1. 配置入口在哪

主要看 mahiro.config.yaml 中 music 段：

• api：音乐接口地址
• autoplay：是否自动播放
• playlist：歌单 ID 列表

这是整个音乐模块的输入源。

2. 最小可用配置

music:
  api: https://api.qijieya.cn/meting
  autoplay: false
  playlist:
    - 1377164042

建议先用一个歌单 ID 跑通流程，再扩展多个歌单。

3. 配置后如何验证

1. 启动本地开发：pnpm dev
2. 打开音乐页或全局播放器
3. 检查是否能正常加载歌曲信息并播放

如果加载了列表但不能播放，优先看接口可达性与音源限制。

4. 常见问题排查

4.1 歌单为空

• playlist 是否为数组
• 歌单 ID 是否有效
• 接口返回是否正常

4.2 有歌曲但无法播放

• 音源链接是否失效
• 浏览器是否阻止自动播放
• 接口是否有跨域/限流问题

4.3 页面有播放器但样式错位

优先检查：

• 当前主题是否影响组件色彩对比
• 移动端宽度是否触发溢出

5. 新手最佳实践

• 先保证 autoplay: false，避免首屏干扰
• 优先配置 1~2 个稳定歌单
• 每次改配置后跑一次 pnpm check

系列导航

新手专栏目录入口