企业官网建设流程全解析

• 移动开发
• 音视频
• 插件系统

MusicFree 是一款插件化、定制化、无广告的免费音乐播放器（Android / Harmony OS），它本身不集成任何音源，搜索、播放、歌单、歌词等能力全部由插件提供。本篇以仓库根目录的 changelog.md 为线索，梳理从 2022 年 10 月的首个测试版到 2025 年 10 月的 v0.6.2 之间每一版的核心改动，并结合 src/core 源码剖析「多语言、音源重定向、倒计时关闭、评论分页、插件 description」等关键能力的底层实现。读完本文，你可以完整掌握 MusicFree 的功能地图、插件协议演进脉络，以及各版本升级前需要注意的兼容性事项。

一、版本总览：从 alpha 到 v0.6.2 的演进主线

MusicFree 的更新记录完整保存在仓库根目录的 changelog.md 中，与 package.json 中的版本号（当前为0.6.2，React Native 依赖版本为0.76.5）相互印证。整体演进可划分为三个阶段：

从迭代频率可以看出，项目早期（2022.10–2023.10）保持每月 1 至 2 个 alpha 版本的快速迭代节奏，几乎所有重大功能骨架（插件协议、本地音乐、下载、歌单、备份恢复）都在这段时期完成；2024 年起进入功能深化与稳定性修复阶段；2025 年则转向体验优化与技术债清理。

二、插件协议演进：MusicFree 的立身之本

changelog 中大量条目围绕插件展开，因为「播放器本身无音源、一切能力由插件提供」是该项目的核心架构。插件本质上是一个满足插件协议的 CommonJS 模块，分页、缓存、播放控制等由 MusicFree 接管，插件开发者只关心输入输出。

2.1 插件协议的关键节点

从 changelog 可以还原插件协议的演进时间线：

• v0.0.1-alpha.1（2023.1.27）：插件协议重大更新，升级后旧插件完全不兼容，需要卸载后重新订阅；
• v0.0.1-alpha.2 / alpha.3：插件订阅与批量导入、插件排序（搜索结果排序）能力落地；
• v0.0.1-alpha.5：新增 Cookie 管理器、一键卸载全部插件；
• v0.1.0-alpha.10（2023.8.13）：协议新增「配置某插件不出现在特定搜索结果页下」，即supportedSearchType字段；
• v0.1.2-alpha.0（2023.11.24）：协议新增「用户变量」（userVariables），使插件可读取用户在 App 内的自定义配置，为自建音乐源 / WebDAV 源插件提供了数据通道；
• v0.2.0（2024.1.21）：支持显示插件作者（author字段）、榜单详情分页、去除插件 URL 必须以.js结尾的限制（可直接使用.json描述文件）；
• v0.4.0（2024.9.1）：插件新增评论区能力，需要插件实现getMusicComments方法；
• v0.6.0（2025.7.24）：插件新增description字段，可嵌入 Markdown 格式的插件说明；插件获取评论支持分页（需插件配合）；修复移动端 axios 库读取的 cookie 与桌面版不一致的问题。

2.2 插件协议的数据结构与能力矩阵

当前插件协议的类型定义完整保存在 src/types/plugin.d.ts 中，其中与 changelog 直接对应的关键字段包括：

在实现侧，src/core/pluginManager/index.ts 中的PluginManager负责插件的加载、安装、更新、排序与启停：

• setup()：启动时扫描插件目录下所有.js文件并创建Plugin实例；当开启basic.lazyLoadPlugin配置时，会优先读取 plugin.cache 缓存实现懒加载，并在启动 10 秒后异步完成剩余插件的挂载——这正是 v0.6.2「优化软件启动速度」的底层实现之一；
• installPluginFromUrl/installPluginFromLocalFile：支持从网络 URL 与本地文件安装插件，安装前通过compare-versions进行版本比较，若已安装同版本插件则静默忽略，若本地已有更新版本则拒绝降级安装；
• getSortedPluginsWithAbility(ability)：按插件顺序筛选具备指定能力的插件，搜索结果、榜单、热门歌单的展示都会依赖这一查询，对应 changelog 中「插件页新增开关，控制是否在榜单、热门歌单、搜索结果中展示对应插件结果」的机制。

2.3 用户变量：插件与 App 的数据通道

v0.1.2-alpha.0 引入的「用户变量」由 src/types/plugin.d.ts 中的IUserVariable描述（key/name/hint），插件声明后，用户即可在插件设置页录入对应配置值。这些值通过 src/core/pluginManager/index.ts 的setUserVariables/getUserVariables读写，并持久化在插件元数据存储中。官方在 changelog 中说明，该能力可以由此实现自建音乐源插件与 WebDAV 源插件。

三、播放核心与音质体系

播放是播放器的本职，changelog 中围绕播放的条目贯穿始终：

• v0.0.1-alpha.6 ~ alpha.11：完善音质功能、支持根据音质下载、新增「播放时被打断」的设置（可暂停或暂时降低音量）；
• v0.1.0-alpha.2：新增倍速播放；
• v0.1.1-alpha.0：音源支持 m3u8；
• v0.2.0：音乐播放栏支持左右滑动切歌、重构播放与数据存储逻辑；
• v0.3.0：新增「自动换源」功能，当插件失效/无法获取播放链接时自动尝试更换其他源的同名歌曲；
• v0.4.0：播放列表歌曲上限从 1500 首调整到 10000 首，重写歌曲排序机制；
• v0.5.0：修复运行一段时间后容易闪退、插件网络请求无法传递 cookie 等问题；
• v0.6.0：优化播放器稳定性，减少闪退/播放自动暂停；修复部分情况下歌词页高亮混乱的问题。

播放解析的核心逻辑位于 src/core/pluginManager/plugin.ts，其顺序是：内存/磁盘缓存 → 插件getMediaSource解析 → 兜底使用音乐项自带的qualitiesURL。其中缓存控制遵循basic.pluginCacheControl配置（cache/no-cache/no-store），离线且配置为no-cache时仍可回退到已缓存音源。

3.1 音源重定向（v0.6.0）

v0.6.0 新增的「音源重定向」允许将某插件实际解析音源的工作委托给另一个插件。这一机制在 src/core/pluginManager/plugin.ts 中体现为：

// 3. 替代插件 const alternativePlugin = Plugin.pluginManager?.getAlternativePlugin(this.plugin) as Plugin | null; const parserPlugin = alternativePlugin?.instance?.getMediaSource ? alternativePlugin : this.plugin; if (alternativePlugin) { devLog("info", "设置了替代插件，实际使用的插件为", parserPlugin.name); }

即：若为插件 A 设置了替代插件 B，且 B 实现了getMediaSource，则 A 解析音源时会改用 B 的解析结果。设置入口在 src/pages/setting/settingTypes/pluginSetting/components/pluginItem.tsx，配置持久化由 src/core/pluginManager/meta.ts 的setAlternativePlugin完成。该功能常被用来在某一音源插件失效时，让另一插件继续提供可用的播放地址。

3.2 播放打断与降低音量幅度（v0.6.0）

v0.6.0「音频被暂时打断时可调节降低音量的幅度」的配置项为basic.tempRemoteDuckVolume，可选值限定为0.3 | 0.5 | 0.8（见 src/types/core/config.d.ts），默认值为0.5。其运行机制在 src/service/index.ts 中：

if (tempRemoteDuckConf === "lowerVolume") { if (paused) { const tempRemoteDuckVolume = Config.getConfig("basic.tempRemoteDuckVolume") ?? 0.5; return RNTrackPlayer.setVolume(1 - tempRemoteDuckVolume); } else { return RNTrackPlayer.setVolume(1); } }

即收到系统RemoteDuck（音频暂时打断）事件后，将音量降为1 - tempRemoteDuckVolume（默认 0.5）；打断结束时恢复满音量。若basic.tempRemoteDuck配置为pause，则会临时暂停并在打断结束后自动恢复播放，相关逻辑同样位于 src/service/index.ts。

四、多语言支持（v0.6.0）

v0.6.0 引入多语言支持。当前仓库内置三种语言包，位于 src/core/i18n/languages：

• zh-cn.json（简体中文，默认）
• zh-tw.json（繁体中文）
• en-us.json（English）

实现上，src/core/i18n/index.ts 通过 Jotai 的currentLanguageAtom管理当前语言，setLanguage(locale)会同步持久化到app.language；翻译函数t(key, args)支持{var}形式的参数插值，例如音源重定向的提示文案「该插件实际使用「{name}」插件解析音乐的音源」就是在运行时通过参数替换完成渲染的。useI18N()Hook 负责在语言切换时触发组件刷新。

五、歌词与本地音乐：从内嵌读取到自动搜索

歌词能力是 MusicFree 的高频迭代点：

• v0.0.1-alpha.9：本地音乐读取内嵌歌词；同目录同名.lrc文件自动作为歌词（v0.0.1-alpha.11）；
• v0.1.0-alpha.10：当前音乐无歌词时可在歌词页搜索歌词；
• v0.1.1-alpha.0：取消原「歌词关联」逻辑，改为拉起「歌词搜索」浮层；
• v0.1.2-alpha.0：新增「关联歌词方式」设置，可切回输入歌曲 ID 关联歌词的老逻辑；
• v0.2.0：歌词页样式改版，新增歌词进度调整、歌词大小调整、歌词翻译、自动搜索歌词；
• v0.4.0：修复歌词翻译错位的问题；
• v0.6.0：略微调大歌词页播放按钮、修复部分情况下歌词页高亮混乱的问题。

本地音乐方面，v0.0.1-alpha.7 至 alpha.11 期间逐步支持：外置 SD 卡扫描、aac/flac/wav/m4a/ogg 等多种格式导入、批量删除（不删除源文件）、自定义下载路径、内嵌封面读取。v0.4.1 曾回滚部分读取本地文件的逻辑以修复桌面歌词开启与颜色修改崩溃等问题；v0.5.0 修复了部分情况下播放本地音乐提示「当前非 Wifi 环境」的问题。

本地音乐的实现集中在 src/core/localMusicSheet.ts，歌词解析与关联逻辑位于 src/core/lyricManager.ts，歌词文本解析工具在 src/utils/lrcParser.ts。

六、歌单与存储机制：两次关键重构

歌单存储是升级时需要特别留意的部分，changelog 明确标注了两次存储机制变更：

• v0.3.0（2024.3.31）：优化存储方式，歌单自动转化为新存储格式；官方提醒「安装新版本后再回退到老版本会导致歌单清空，请谨慎升级」；
• v0.4.0（2024.9.1）：再次修改歌单存储机制，官方同样标注「建议谨慎更新」，并同步将单歌单歌曲上限从 1500 首提升至 10000 首、重写歌曲排序机制。

从源码看，歌单存储由 src/core/musicSheet 模块承载：其中 storage.ts 负责歌单数据的读写与持久化，migrate.ts 负责旧版本歌单数据的迁移，sortedMusicList.ts 实现按加入时间等维度的排序（对应 v0.3.0「歌单内支持按照加入时间排序」）。与歌单配套的功能还包括：

• v0.2.0「新增收藏歌单功能」；
• v0.3.0「首页新建歌单旁新增导入歌单按钮，自动寻找具有导入歌单功能的插件」；
• v0.6.0「本地歌单高亮正在播放的歌曲」「新增定位按钮跳转到正在播放的音乐」；
• 歌单信息编辑（名称、封面）、歌单批量编辑、歌单内模糊搜索（v0.1.0-alpha.6 支持英文大小写模糊搜索）等。

七、桌面歌词、定时关闭与通知栏

7.1 桌面歌词与悬浮窗

v0.1.2-alpha.0 新增桌面歌词功能，需先在手机系统设置中授予悬浮窗权限；v0.4.1 修复了桌面歌词无法开启、修改颜色闪退的问题。桌面歌词的样式配置（位置、字号、颜色、背景色、透明度、对齐方式）对应配置项lyric.*系列，见 src/types/core/config.d.ts。Android 侧的悬浮窗渲染由原生模块实现，位于 android/app/src/main/java/fun/upup/musicfree/lyricUtil。

7.2 倒计时与定时关闭

「定时关闭」自 v0.0.1-alpha.11 起出现在侧边栏，v0.6.0 对其做了重要增强：支持倒计时结束后，等歌曲播放完成再退出应用。该能力的实现集中在 src/utils/scheduleClose.ts，并结合 react-native-background-timer 实现后台计时；设置入口位于 src/components/panels/timingClose.tsx。

7.3 通知栏控制

v0.2.0 新增「通知栏显示关闭按钮」设置（配置项basic.showExitOnNotification）。通知栏相关的播放控制由 react-native-track-player 提供，并配套 Android 原生能力（android/app/src/main/java/fun/upup/musicfree 下的 Utils/Mp3Util 等模块）。v0.0.1-alpha.11 还修复过本地音乐在通知栏不显示标题的问题。

八、备份、WebDAV 与下载

• v0.0.1-alpha.2：新增备份 & 恢复，可将本地歌单和插件备份为一个 JSON 文件，也可从本地文件或网络恢复——对应实现为 src/core/backup.ts；
• v0.2.0：支持 WebDAV 备份 & 播放，依赖webdavnpm 包（见 package.json），配置项为webdav.url/webdav.username/webdav.password（src/types/core/config.d.ts），并配套「恢复时是覆盖还是合并」的backup.resumeMode配置；
• 下载：v0.0.1-alpha.10 支持自定义下载路径；v0.4.0 修复下载文件时转移文件名保留字符；下载实现位于 src/core/downloader.ts。

九、技术栈升级与兼容性提醒

9.1 React Native 大版本升级记录

changelog 明确记录了两轮 RN 大版本升级：

当前 package.json 中react-native为0.76.5，与 v0.5.0 升级后保持一致；工程同时使用 Expo SDK 52 系列模块（文件系统、文档选择、开机屏、常亮等）。

9.2 配置体系的模块化

从 v0.5.0/v0.6.0 开始，配置体系被重构为「点分键 + MMKV 存储」的形式。src/core/appConfig.ts 中的AppConfig类提供getConfig/setConfig读写配置，并内置两轮 schema 迁移（$schema从 0 → 1 → 2），将旧版本setting.*嵌套结构自动迁移到新的点分键结构；完整的键定义在 src/types/core/config.d.ts，可按前缀归类：

• basic.*：播放、下载、网络、打断、插件更新策略等基础行为；
• lyric.*：歌词页与桌面歌词的样式与行为；
• theme.*：背景、模糊、透明度、自定义颜色、跟随系统深色；
• webdav.*/backup.*/plugin.*：WebDAV 配置、备份恢复模式、插件订阅地址；
• debug.*：错误日志 / 追踪日志 / 开发日志开关。

十、升级路径建议与注意事项

综合 changelog 中的官方提示，升级时需重点关注以下几点：

1. v0.3.0 / v0.4.0 的歌单存储变更：两次均改变歌单存储机制，升级后回退旧版本可能导致歌单清空，请先备份（设置中通过 src/core/backup.ts 导出 JSON 备份）；
2. v0.5.0 的安卓版本门槛：升级到 React Native 0.76.5 后仅支持安卓 7.0+，老设备用户不要升级；
3. 插件兼容性：v0.0.1-alpha.1 曾有一次不兼容旧插件的协议变更（需卸载后重新订阅）；v0.6.0 新增的评论分页、description字段需要插件配合，旧插件不受影响但无法展示新能力；
4. v0.6.2 优化了启动速度：实现上依赖插件懒加载（basic.lazyLoadPlugin配置 + plugin.cache 缓存）与核心代码重构（changelog v0.6.0「重构了核心部分代码逻辑，后续维护起来成本会小一些」）。

结语

通过 changelog 与源码的对照可以清晰看到，MusicFree 的演进遵循「插件协议先行、播放与歌词深化、稳定性与体验收尾」的节奏：早期快速确立插件化架构与基础能力，中期补充 WebDAV、桌面歌词、自动换源等进阶功能，后期则在多语言、音源重定向、启动性能与播放稳定性上做精修。对于使用者，本文梳理的兼容性提示（尤其是两次歌单存储变更与安卓 7.0 门槛）可以帮助你在升级时规避数据风险；对于插件开发者，src/types/plugin.d.ts 中完整的类型定义与 src/core/pluginManager 的实现则是理解插件协议、编写或适配插件的最佳参考。

• 移动开发
• 音视频
• 插件系统