Xiaomusic终极安装指南：5分钟让小爱音箱变身智能音乐中心

Xiaomusic是一个专为小爱音箱设计的开源音乐播放系统，通过yt-dlp工具实现智能音乐下载和播放管理，让你的小爱音箱瞬间升级为功能强大的个人音乐中心。本指南将用最简单的方式带你完成安装配置，无需任何编程基础。

🎯 安装前准备

在开始安装之前，请确保你的环境满足以下基本要求：

• 操作系统：支持Windows、Linux、macOS
• Python版本：Python 3.7及以上
• 网络环境：稳定的互联网连接
• 小爱设备：可连接的小爱音箱设备

🐳 Docker一键部署（推荐新手）

Docker是最简单快捷的部署方式，无需配置复杂的Python环境：

基础Docker命令

docker run -p 58090:8090 -e XIAOMUSIC_PUBLIC_PORT=58090 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic

Docker Compose部署（适合长期使用）

services:
  xiaomusic:
    image: hanxi/xiaomusic
    container_name: xiaomusic
    restart: unless-stopped
    ports:
      - 58090:8090
    environment:
      XIAOMUSIC_PUBLIC_PORT: 58090
    volumes:
      - /xiaomusic_music:/app/music
      - /xiaomusic_conf:/app/conf

关键配置说明：

• conf目录存放配置文件，music目录存放音乐文件
• 如果提示目录不存在，先执行：mkdir -p /xiaomusic_{music,conf}
• 访问地址：http://你的设备IP:58090

🐍 Python pip安装方式

如果你已经安装了Python环境，可以使用pip快速安装：

pip install -U xiaomusic
xiaomusic

系统默认监听8090端口，访问http://localhost:8090即可进入控制界面。

⚙️ 首次配置指南

第一步：获取项目代码

git clone https://gitcode.com/GitHub_Trending/xia/xiaomusic
cd xiaomusic

第二步：基础配置

复制配置文件模板：

cp config-example.json config.json

第三步：Web界面配置

1. 打开浏览器访问控制面板
2. 在设置页面输入小米账号和密码
3. 保存配置后系统会自动获取设备列表

如图所示，Xiaomusic提供了完整的控制功能：

• 左侧设备管理：关联小爱音箱，设置关机时间
• 中部歌曲列表：浏览本地和网络歌曲，支持双击播放
• 底部播放控制：进度条、播放模式、音量调节等

🎵 核心功能体验

语音控制口令

安装完成后，你可以直接对小爱同学说：

• "播放歌曲" - 播放本地歌曲
• "播放歌曲+歌名" - 如"播放歌曲周杰伦晴天"
• "上一首"、"下一首" - 切换歌曲
• "单曲循环"、"全部循环" - 切换播放模式
• "关机"、"停止播放" - 控制音箱状态

音乐格式支持

• MP3、FLAC、WAV、APE、OGG、M4A
• 本地音乐自动扫描，网络音乐智能下载

🔧 常见问题解决

端口冲突问题

如果58090端口被占用，可以修改为其他端口：

docker run -p 8080:8090 -e XIAOMUSIC_PUBLIC_PORT=8080 -v /xiaomusic_music:/app/music -v /xiaomusic_conf:/app/conf hanxi/xiaomusic

设备连接问题

• 确保小爱音箱与安装Xiaomusic的设备在同一网络
• 首次配置必须在Web界面正确输入小米账号密码

💡 使用小贴士

1. 快速搜索：在控制面板使用搜索功能快速找到歌曲
2. 播放列表：创建个人播放列表，方便快速播放
3. 多设备切换：支持在不同小爱设备间无缝切换

🚀 进阶功能探索

插件系统

Xiaomusic提供了丰富的插件支持，在plugins/目录下可以找到各种功能插件，如HTTP请求处理、音量控制等。

网络歌单

支持JSON格式网络歌单配置，可以轻松导入电台和共享歌单。

✅ 安装完成检查

完成以上步骤后，你的Xiaomusic应该已经正常运行。打开浏览器访问控制面板，尝试播放一首歌曲，体验小爱音箱的全新音乐播放能力！

通过这个简单的安装过程，你已经成功将普通的小爱音箱升级为功能强大的智能音乐中心。无论是本地音乐播放还是网络音乐下载，Xiaomusic都能为你提供极致的音乐体验。