HarmonyOS音乐播放器开发实战：从AVPlayer到后台播放的完整指南

做HarmonyOS App开发，最容易被低估的项目就是音乐播放器。乍一听，播放器不就是加载一个音频文件、点一下播放键让声音出来吗？可真把一个鸿蒙音乐播放机应用完整做下来，从权限声明、本地文件扫描、音频播放接口选型、页面状态同步，到通知栏控制、后台长任务、锁屏交互，每个环节都有一堆细节要处理。这篇博文把我在鸿蒙平台上从零到一开发音乐播放应用的全过程整理出来，包括技术选型、工程结构、核心实现思路和真机调试的实战经验，希望能给正在做HarmonyOS App开发、尤其是准备碰播放器类项目的开发者一些参考。

先说结论：HarmonyOS音乐播放器不是不能做，而是不能按普通列表页面那套思路去做。它的难点不在页面UI，而在播放链路、生命周期和状态同步。你只要把这几条线想清楚，后面写起代码来会顺得多。

1. 为什么用HarmonyOS做音乐播放器：技术选型与项目准备

1.1 播放器App在鸿蒙生态里的真实定位

很多开发者有个误区，觉得音乐播放器是个"练手Demo"，随便调个播放接口就行。但我实际做下来发现，音乐播放器在HarmonyOS里其实是一个非常适合用来检验开发功力的"复合型项目"。它要同时牵扯媒体框架、文件系统、通知机制、后台任务、UI状态管理，还涉及权限申请和生命周期调度。任何一个环节没理顺，都会在真机上暴露问题。

而且鸿蒙目前的生态正处于设备融合阶段，手机、平板、智慧屏都在用同一套分布式能力。音乐播放器做出来之后，天然适合往多设备流转和卡片服务方向扩展。也就是说，你现在做的每一块基础能力，后面都能接得住。这也是我选这个项目作为HarmonyOS App开发实战切入点的原因。

1.2 技术栈确定：ArkTS、ArkUI与API 9+的选择逻辑

开发语言我选了ArkTS，这是鸿蒙原生推荐的语言。不少从Android转过来的开发者会纠结要不要用Java或者C++写，实际上在HarmonyOS应用层开发，ArkTS已经足够覆盖播放器这类项目，而且架构上更贴合鸿蒙的声明式UI模型。

UI框架用的是ArkUI声明式开发，页面结构、组件状态、事件绑定都在一个组件里写，开发效率高很多。如果你之前写过Flutter或者SwiftUI，上手ArkUI几乎没有什么心理负担。

API版本方面，我建议直接选API 9或更高版本。音乐播放相关的@ohos.multimedia.media模块在API 9之后已经比较稳定，AVPlayer（通用音视频播放器）替代了早期的AudioPlayer，接口更统一，回调更清晰。如果你的设备系统是HarmonyOS 4.2，那API 10、API 11的兼容性也都没问题。

1.3 工程搭建：DevEco Studio配置与项目骨架

创建项目这块有几点值得注意：

• 新建工程时，模板选择"Empty Ability"即可，播放器需要的页面后面自己加，不需要选带列表的模板。
• 包名建议用类似com.example.musicplayer的格式，后面做分布式能力和卡片时，包名的规范程度会影响调试体验。
• 编译SDK版本和兼容SDK版本要分清。compileSdkVersion用你本机最新的即可，兼容版本可以适当调低，让应用能在更多HarmonyOS设备上跑。

我建完工程后的目录结构大致是这样：

code复制entry/src/main/ets/
├── entryability/
│   └── EntryAbility.ets
├── pages/
│   ├── Index.ets          // 首页（最近播放、歌单入口）
│   ├── PlayListPage.ets    // 播放列表页
│   └── PlayerPage.ets      // 全屏播放页
├── model/
│   ├── Song.ets            // 歌曲数据模型
│   └── PlayList.ets        // 播放列表管理器
├── common/
│   └── PlayerManager.ets   // 播放器全局管理类
└── resources/

这套结构不复杂，但把"页面"和"逻辑"分开了。尤其是PlayerManager这类全局管理类，一定要独立出来。播放器的状态（是否播放、当前歌曲、播放进度）被多个页面共享，如果每个页面都在自己内部创建播放器实例，那后面的状态同步会非常痛苦。

提示：如果你在搜索结果里搜到很多老教程还在用AudioPlayer，注意从API 9开始优先使用AVPlayer。虽然AudioPlayer还没有完全废弃，但AVPlayer才代表后续演进方向，建议从一开始就站在新接口这边。

2. 播放核心链路：从AVPlayer状态机到全局播放器管理

2.1 音频播放接口选型：AVPlayer还是AudioPlayer

如果你在鸿蒙社区搜过音频播放，一定