xiaomusic 版本演进全解读从 v0.1.1 到 v0.6.1 的功能迭代、架构重构与安全修复记录【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic本文以仓库内docs/issues/changelog.md版本日志为骨架逐阶段梳理 xiaomusic小爱音箱音乐播放项目从 2023 年 10 月首个版本到 2026 年 6 月停止维护的完整技术演进史。你将了解到该项目如何围绕语音口令 → 音乐下载 → 小爱播放这一核心链路逐步构建出定时任务、网络歌单、多音源集成、多设备播放、缓存与安全加固等能力并看到每条变更在仓库源码中的对应实现。读完本文你可以对照版本号回溯任一功能的引入时间、设计动机与代码位置也可以据此判断升级路径与已知问题。一、版本日志概览项目生命周期与技术主线xiaomusic 的版本日志docs/issues/changelog.md记录了从v0.1.12023-10-14到v0.6.12026-06-09共约 120 个版本号的迭代。根据日志节奏项目演进可划分为四个阶段阶段版本区间时间跨度主题早期雏形v0.1.x2023-10 ~ 2024-07核心播放链路、口令系统、配置体系成形功能爆发v0.2.x ~ v0.3.x2024-07 ~ 2025-05多设备、定时任务、主题体系、歌单管理、收藏、下载工具重构整合v0.4.x2025-06 ~ 2026-01大量 Refactor、API 拆分、登录与 TTS 重构、插件系统网络音源与收尾v0.5.x ~ v0.6.x2026-03 ~ 2026-06MusicFree/LX Server 集成、安全修复、停止更新[!NOTE] 版本日志本身只是变更清单本文在保留全部关键条目Feat/Fix/Refactor/Perf/Security的基础上结合仓库源码xiaomusic/ 目录补上了各功能点的实现细节供读者对照查阅。二、v0.1.x从能播放到可配置的奠基期v0.1.x 阶段2023-10 ~ 2024-07完成了项目从个人脚本到可配置服务的关键转变。2.1 核心播放链路成型最早的版本日志条目v0.1.1 ~ v0.1.32023-10没有具体说明只有v0.1.4记录了首个明确的修复error when play next播放下一首报错。此后项目围绕下载 → 播放链路持续修复v0.1.12修复set volume failed音量设置失败v0.1.38#70下一首歌曲不存在时从播放列表中删除并继续找下一首——这一逻辑至今保留在播放队列管理中v0.1.88升级 yt-dlp 到 2024.07.01修复部分型号关机失败的问题[!TIP] 音乐下载依赖 yt-dlp 是项目的核心设计README 中明确音乐使用 yt-dlp 下载因此日志中多次出现升级 yt-dlp 以解决下载问题的记录例如 v0.3.50 中更新 yt-dlp解决 B 站下载问题#279。2.2 配置体系从环境变量走向配置文件v0.1.x 阶段配置项大多以环境变量形式引入源码 xiaomusic/config.py 中至今保留了这些变量的定义与默认值例如v0.1.54#76新增XIAOMUSIC_MUSIC_PATH_DEPTH配置生成播放列表的目录深度默认 10并新增XIAOMUSIC_CONF_PATH允许配置目录与下载目录分开v0.1.54#74配置目录默认可独立设置不配置时使用下载目录v0.1.77#52支持配置模糊匹配本地歌曲——对应源码中的enable_fuzzy_match默认 true与fuzzy_match_cutoff默认 0.6两个配置项v0.1.84config.json支持更多配置选项新增XIAOMUSIC_STOP_TTS_MSG配置关机提示音v0.1.92启动参数新增--port配置监听端口外网访问端口可独立配置——对应port默认 8090与public_port默认 58090# xiaomusic/config.py 中保留下来的 v0.1.x 时期配置项 music_path: str os.getenv(XIAOMUSIC_MUSIC_PATH, music) conf_path: str os.getenv(XIAOMUSIC_CONF_PATH, conf) music_path_depth: int int(os.getenv(XIAOMUSIC_MUSIC_PATH_DEPTH, 10)) enable_fuzzy_match: bool os.getenv(XIAOMUSIC_ENABLE_FUZZY_MATCH, true).lower() true fuzzy_match_cutoff: float float(os.getenv(XIAOMUSIC_FUZZY_MATCH_CUTOFF, 0.6))2.3 口令系统与版本规范v0.1.93#105新增自定义口令功能这是项目最重要的扩展点之一。源码 xiaomusic/config.py 的default_user_key_word_dict()提供了两个示例测试自定义口令 →exec#code1(hello)、测试链接 →exec#httpget(...)自定义口令以exec#前缀路由到插件执行v0.1.94优化多设备接口执行效果尽量做到同时执行新增参数配置强制打断小爱说话对应enable_force_stopv0.1.96使用 commitizen 管理版本号、规范版本管理——此后日志的格式趋于统一v0.3.02024-07-14使用 FastAPI 替换 Flask解决多线程问题这是后端架构的重要转折点。当前 xiaomusic/api/app.py 即为 FastAPI 应用路由拆分到 xiaomusic/api/routers/ 目录三、v0.3.x功能爆发期主题、定时任务、歌单与收藏体系全面铺开v0.3.x2024-07 ~ 2025-05是迭代最密集的阶段日志中 Feat 条目数量最多几乎每周都有新能力落地。3.1 前端主题体系项目围绕 Web 控制台先后开发了多个主题源码中对应的静态资源位于 xiaomusic/static/v0.3.34#172新增 pure 主题vue elementUI→ xiaomusic/static/pure/v0.3.74#383新增 Tailwind 主题 → xiaomusic/static/tailwind/v0.3.37#180Pure 主题设置中心新增主题音乐列表样式选择、夜间模式v0.3.38#214/#216新增 XMusicPlayer 播放器主题v0.3.99#568/#569新增 SoundScape 主题 → xiaomusic/static/soundSpace/并兼容移动端v0.3.100#577v0.4.16删除怀旧主题v0.4.24#775新增适配 iPhone 主题3.2 播放控制与歌单管理v0.3.28#87新增歌曲收藏功能——对应口令加入收藏/收藏歌曲add_to_favorites与取消收藏del_from_favoritesv0.3.31#90新增播放上一首歌曲功能、所有歌曲列表v0.3.33#171支持继续播放continue_play默认 truev0.3.38#158新增口令【播放列表第几个列表名】来播放列表里的第几个v0.3.49#277新增单曲播放和顺序播放功能设置播放类型支持配置语音提示词v0.3.54#273新增最近新增歌单v0.3.57新增搜索播放口令用于生成临时播放列表v0.3.38使用 opencc 将歌曲名转化为简体#192、搜索多个结果并更新当前播放列表#185口令匹配机制在 xiaomusic/command_handler.py 中实现match_cmd先尝试完全匹配再按key_match_order优先级做正则模糊匹配(.*)关键词(.*)命中后通过getattr路由到主类的对应方法。所有默认口令定义在default_key_word_dict()中# xiaomusic/config.py def default_key_word_dict(): return { 下一首: play_next, 上一首: play_prev, 单曲循环: set_play_type_one, 全部循环: set_play_type_all, 随机播放: set_play_type_rnd, 单曲播放: set_play_type_sin, 顺序播放: set_play_type_seq, 分钟后关机: stop_after_minute, 刷新列表: gen_music_list, 加入收藏: add_to_favorites, 收藏歌曲: add_to_favorites, 取消收藏: del_from_favorites, 播放列表第: play_music_list_index, 删除歌曲: cmd_del_music, }3.3 定时任务体系#182 系列v0.3.38#182新增定时任务功能是 v0.3.x 最重大的功能之一。随后围绕它持续扩展v0.3.45定时任务支持设置音量、播放歌单口令支持配置v0.3.49定时任务支持设置播放类型v0.3.76#182新增重新初始化的定时任务、开启/关闭拉取对话记录的定时任务v0.3.81#182定时任务支持工作日和休息日——这是结合节假日数据holiday/ 目录存放 2007~2027 年节假日 JSON实现的v0.4.6定时任务支持选多个歌曲组成一个歌单播放源码 xiaomusic/crontab.py 完整实现了这套体系基于 APScheduler 的AsyncIOScheduler通过CustomCronTrigger在 cron 表达式后追加#workday或#offday注释来限定工作日/休息日并调用 xiaomusic/holiday.py 的is_working_day/is_off_day判定。# xiaomusic/crontab.py 中的工作日/休息日判断核心 if self.check_workday: valid is_working_day(year, month, day) else: # check_offday valid is_off_day(year, month, day) if valid: return next_time else: return self.get_next_fire_time(next_time, next_time)任务类型支持stop关机、play播放歌曲、play_music_list播放歌单、play_music_tmp_list临时歌单、tts语音播放、refresh_music_list刷新列表、set_volume音量、set_play_type播放类型、set_pull_ask拉取对话记录开关、refresh_web_music_list刷新网络歌单、reinit重新初始化等同时内置每日凌晨 3 点清理临时文件的任务。3.4 下载工具与文件管理v0.3.38新增批量下载歌曲工具、yt-dlp cookies 文件参数支持、musicinfos批量查询接口v0.3.56#266tag 信息支持写入歌曲文件开启 gzip 压缩v0.3.57优化批量下载工具命名和下载高码率音频新增ignore_tag_dirs设置项用于忽略目录下标签信息解决挂载 alist 目录的问题v0.3.59下载完成之后修改文件权限为 755#316v0.3.83#487支持 B 站合集和收藏下载v0.3.88新增歌单合并工具文件管理工具集中在 xiaomusic/utils/file_utils.py 与 xiaomusic/utils/music_utils.py下载逻辑在 xiaomusic/utils/network_utils.py下载相关 API 在 xiaomusic/api/routers/file.py。3.5 播放体验与性能优化v0.3.x 大量迭代围绕播放延迟播放时长获取缓存展开日志中反复出现相关修复v0.3.14优化播放延迟问题新增配置下一首播放的延迟秒数——对应delay_sec配置项v0.3.84进一步支持负数延迟用于解决播放下一首时会播放上一首开头几秒的问题v0.3.12优化获取文件播放时长接口v0.3.18#135修复获取不到播放时长时只播放 3 秒的问题v0.3.38文件转换逻辑延迟到读取文件的时候#218新增 tags 缓存#193v0.3.56播放失败设置重试次数 10 次解决设备失联后无限重试的问题v0.3.68#338增加均衡歌曲响度可选——对应loudnorm配置v0.3.71#340非播放中也返回歌曲时长v0.3.78优化获取时长的方式监控文件夹仅对音乐格式生效#441v0.3.80#462支持配置最大搜索歌曲数量3.6 设备兼容与登录v0.3.50统计设备型号v0.3.77OH2P、v0.3.80OH2、v0.3.88X6A等版本持续新增小爱音箱型号支持日志中还有大量修复型号 X4B/LX05/M01 不能播放的记录v0.3.82修复节假日文件没有打包到 docker 镜像里的问题v0.3.90~v0.3.97多次尝试修复登录问题#547 等体现小米账号登录链路的不稳定性v0.3.97升级 miservice 依赖四、v0.4.x大规模重构与登录、TTS、插件体系重建v0.4.x2025-06 ~ 2026-01以重构为主线日志中 Refactor 条目显著增多。4.1 核心模块拆分v0.4.0重构 xiaomusic.py 模块、重构拆分 httpserver 文件、重构拆分 utils 文件。当前仓库中已看不到单一的 httpserver.py而是拆分为 xiaomusic/api/FastAPI 应用与路由、xiaomusic/device_manager.py多设备管理、xiaomusic/device_player.py设备播放1328 行核心逻辑、xiaomusic/conversation.py对话记录拉取等模块v0.4.7重构播放时长获取规则#668修改 cache 目录v0.4.9修改 api 接口、新增清空临时目录接口4.2 登录链路与 TTS 反复迭代v0.4.x 的 Fix 条目高度集中在登录报错v0.4.8支持配置 cookie接入 edge-tts 解决文字转语音问题#642——对应配置edge_tts_voice默认zh-CN-XiaoyiNeuralv0.4.10设置 token 到 account#680、把 cookie 到 .mi.token#676、修复 ws 连接错误v0.4.13#688登录支持仅填 cookiev0.5.6#875优化认证登录重试机制新增 token 过期模拟调试接口解决设备无故掉线问题此外 xiaomusic/qrcode_login.py468 行实现了v0.4.23#750加入的二维码登录功能。4.3 插件与扩展能力v0.4.0增加 musicfree 插件集成功能v0.4.5在线播放功能优化新增 AI 智能提取用户口令#654——对应 xiaomusic/utils/openai_utils.pyv0.4.13#690网络歌单插件功能更新v0.4.22新增 HMusic 客户端插件体系在 xiaomusic/js_plugin_manager.py近 3000 行与 xiaomusic/plugin.py 中实现仓库根目录的 check_plugins.py 用于检查插件。4.4 安全与 API 增强v0.4.13编译出 arm/v7 架构的镜像v0.4.23新增/getplayerstatusAPI 获取完整播放状态#747/downloadonemusicAPI 支持playlist_name与dirname参数#749/#751/#756v0.3.87新增 websocket 接口获取当前播放状态 → xiaomusic/api/websocket.py五、v0.5.x网络音源集成与安全加固走向收尾v0.5.x2026-03 ~ 2026-05聚焦第三方音源MusicFree / LX Server接入同时密集发布安全修复。5.1 MusicFree 与 LX Server 集成v0.5.1#809新增 MusicFree 插件v0.5.2后台自动切换 MusicFree 插件 / LX Server 接口#829后端自动识别 MusicFree 与 LX Server#832优化 MusicFree 插件和 LX Server 接口#838v0.5.0#798/#802lxserver 适配与接口功能拓展高级设置增加口令平台偏好设置#804方便语音指令播放时指定平台v0.5.3#848/#849后端和前端新增 MusicFree 搜索歌单功能针对 LX Server 接口增加搜索歌单功能#842v0.5.8#886/#887完善 LX Server 播放链接解析流程修复 LX 在未换源解析完成的情况跳歌在线音乐核心逻辑位于 xiaomusic/online_music.py1693 行前端设置页在 xiaomusic/static/onlineSearch/。5.2 搜索与多结果选择v0.5.3#863新增小爱音箱语音反馈及后端检测播放 url 有效性新增语音口令搜索歌单功能#855/#856v0.5.3#864新增搜索多结果选择功能v0.5.7#881新增是否开启多结果选择功能开关v0.5.7#880播放本地音乐支持一条指令完成搜索选择v0.5.4#868增加搜索成功后的语音提示选择对应源码配置# xiaomusic/config.py 中的多结果选择相关配置 enable_multi_result_selection: bool os.getenv( XIAOMUSIC_ENABLE_MULTI_RESULT_SELECTION, true).lower() true multi_result_action: str os.getenv(XIAOMUSIC_MULTI_RESULT_ACTION, random) fuzzy_match_max_results: int int(os.getenv(XIAOMUSIC_FUZZY_MATCH_MAX_RESULTS, 100))multi_result_action支持random随机播放与first从第一个开始播放两种兜底策略多结果选择时用户可回复第一个/第几个完成选择见 xiaomusic/command_handler.py 中select_index的匹配逻辑。5.3 缓存与触屏版改进v0.5.7#878后端增加缓存功能默认缓存大小 500M当前歌曲 20 秒开始缓存下一首支持随机播放的缓存命中——对应cache_max_size_mb默认 500、cache_song_name等配置缓存目录默认music/cachev0.5.3#850支持自定义temp_path路径临时文件不再依赖music_path挂载——对应temp_path配置默认music/tmpv0.5.3#846增加免签发 Web App 功能PWA三种添加桌面方式v0.5.3#840默认播放页面新增快进快退按钮、倍速播放v0.5.3#851增强 OGG 封面解析支持 FLAC 二进制结构的metadata_block_picturev0.5.8#889增加触屏版封面选择5.4 安全修复专项v0.5.x 密集安全加固v0.5.1#819修复插件 exec 中eval导致任意代码执行漏洞v0.5.1#820修复safe_join_path前缀检查绕过导致的路径穿越漏洞——该函数在 xiaomusic/utils/file_utils.py 中实现用于确保拼接后的路径始终落在安全根目录内被下载、监控等模块广泛调用v0.5.1#815修补 url 的 base64 编码v0.5.8#891为路径包含检查增加 trailing separatorCWE-22v0.5.0#793移除日志和控制台中敏感凭据的明文输出v0.5.0#801启用安全访问后增加 cookie5.5 杂项修复v0.5.4#871执行命令前先停止小爱避免播放不支持提示对应 xiaomusic/command_handler.py 中group_force_stop_xiaoai()的调用v0.5.4#866修复小爱触屏音箱歌曲封面及歌词显示v0.5.8#885修复 Python 3.10 环境下asyncio.timeout导致的 AttributeErrorv0.5.8#883修复同一账号下多台小爱中一台会莫名小music收到或静音但指示灯闪烁的问题六、v0.6.x项目收尾与维护状态v0.6.02026-05-30项目停止更新v0.6.12026-06-09移除项目中所有赞赏/收款码相关内容至此xiaomusic 的版本史画上句号。README 顶部也同步了停止维护通知建议后续迁移到社区接力项目。对仍在使用或计划部署该项目的读者需要注意版本选择若需要最新功能缓存、多结果选择、MusicFree/LX Server应选择 v0.5.x 系列若要规避已知安全漏洞插件 eval、路径穿越应至少升级到 v0.5.1已知遗留问题登录链路在小爱音箱型号间差异较大日志中多次出现尝试修复登录问题遇到掉线可参考 v0.5.6 引入的重试机制与 token 过期调试接口排查配置参考完整配置项可对照 config-example.json 与 xiaomusic/config.py 中的默认值查阅七、结语从版本日志读懂项目设计脉络纵观 changelogxiaomusic 的技术演进有一条清晰的主线口令层xiaomusic/command_handler.py从 v0.1.93 的自定义口令到 v0.3.49 的播放类型口令、v0.3.76 的删除歌曲口令、v0.5.3 的搜索歌单口令最终形成一套完全匹配 优先级模糊匹配 激活命令过滤的完整解析链播放层xiaomusic/device_player.py从单曲播放演进到单曲循环/全部循环/随机/顺序四种模式叠加延迟播放含负数、继续播放、失败重试、缓存预加载等机制调度层xiaomusic/crontab.py定时任务从简单关机扩展到播放、音量、播放类型、对话拉取开关并支持工作日/休息日判定音源层从 yt-dlp 下载 → 网络歌单 → MusicFree/LX Server 第三方音源走向开放生态安全层路径穿越CWE-22、插件代码执行、敏感凭据输出等漏洞的持续修复提示自建服务接入公网时必须开启密码与 Basic Auth这份版本日志不仅是变更清单更是理解 xiaomusic 架构演进的索引。对照 xiaomusic/ 源码阅读可以快速定位每个版本决策背后的实现细节。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考