简介本资源是一份基于鸿蒙HarmonyOSArkTS开发的轻量化云音乐播放应用源码包面向鸿蒙初学者、移动端开发者及国产操作系统技术实践者聚焦音乐类应用核心功能实现解决从UI构建、状态管理到音频控制的典型开发问题。压缩包共19个文件含7个核心ets页面与逻辑组件、4个json配置与数据模拟文件、2个json5构建配置、1个ts工具函数及1个png图标等整体仅22KB结构精简、模块边界清晰便于快速理解ArkTS项目组织范式与响应式开发流程。已有197人学习下载适合用于鸿蒙应用开发入门实践、组件化架构学习或课程实验参考。读者可直接运行调试完整掌握推荐页渲染、关键词搜索、播放器生命周期控制、多模式播放列表管理等端到端实现细节并通过package.json、build-profile.json5等配置文件深入理解鸿蒙工程构建体系。1. 鸿蒙云音乐应用开发为什么从零写一个「能播、能搜、能换肤」的 HarmonyOS 音乐 App 比想象中更可控这不是一个“移植安卓音乐 App 到鸿蒙”的缝合项目而是一次面向 ArkTS Stage 模型的原生开发实践——用官方推荐的 DevEco Studio 4.1、API Version 10即 SDK 10、基于 ohos.app.ability.ServiceExtensionAbility 实现后台音频服务配合 ohos.multimedia.audio.AudioPlayer 控制播放再用 ohos.file.fs 管理本地缓存。它解决的是真实落地中的三个卡点如何让音频在锁屏/切后台后持续播放不中断、如何让搜索结果实时响应且不卡 UI 主线程、如何让深色/浅色主题切换真正影响所有自定义组件而非仅系统控件。适合已掌握 ArkTS 基础语法、熟悉 DevEco Studio 工程结构、但尚未完整跑通「前台界面 后台服务 资源持久化」闭环的开发者。如果你正卡在「点击播放按钮没反应」「切到桌面音乐就停」「换主题后歌词页还是白底」这类问题上这篇笔记就是为你写的血泪复盘。2. 从 DevEco Studio 创建工程到首屏渲染Stage 模型下的最小可运行骨架2.1 创建适配 API Version 10 的空工程并确认关键配置打开 DevEco Studio 4.1.2必须 ≥ 4.1否则不支持ohos.app.ability.ServiceExtensionAbility新建 Project → 选择 “Empty Ability” → 语言选 ArkTS → Minimum SDK 选 API 10 → 包名按规范填写如com.example.hmonmusic。创建完成后检查build-profile.json5中是否含以下关键字段{ apiType: stageMode, compileSdkVersion: 5.0.0(10), compatibleSdkVersion: 5.0.0(10) }提示apiType: stageMode是 Stage 模型的开关若为faFeature Ability则后续无法使用 ServiceExtensionAbilitycompileSdkVersion必须显式指定为5.0.0(10)不能写5.0.0或10否则编译报错Unsupported API version。2.2 替换默认 Page 并实现基础音乐列表页删除src/main/ets/pages/Index.ets新建src/main/ets/pages/MusicListPage.ets内容如下// src/main/ets/pages/MusicListPage.ets import router from ohos.router; import { MusicItem } from ../model/MusicItem; Entry Component struct MusicListPage { State musicList: MusicItem[] [ { id: 1, title: 山海, artist: 草东乐团, duration: 04:23 }, { id: 2, title: 想见你想见你想见你, artist: 八三夭, duration: 03:58 } ]; build() { Column({ space: 12 }) { Text(我的音乐) .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 20 }) List({ space: 8 }) { ForEach(this.musicList, (item: MusicItem) { ListItem() { Row({ space: 12 }) { Image($r(app.media.icon_music)) .width(48) .height(48) .borderRadius(8) Column({ space: 4 }) { Text(item.title) .fontSize(16) .fontWeight(FontWeight.Medium) Text(item.artist) .fontSize(12) .fontColor(Color.Gray) } Text(item.duration) .fontSize(12) .fontColor(Color.Gray) .alignSelf(ItemAlign.End) } .onClick(() { // 点击跳转播放页传入歌曲 ID router.pushUrl({ url: pages/PlayerPage, params: { musicId: item.id } }); }) } }, item item.id) } .listDirection(Axis.Vertical) .height(100%) } .padding({ left: 20, right: 20 }) } }逻辑说明MusicItem是自定义类型需在src/main/ets/model/MusicItem.ets中定义含id,title,artist,duration字段Entry和Component是 ArkTS 组件声明必需装饰器ForEach渲染列表时item item.id是 key 生成函数必须唯一且稳定否则列表滚动会复用错误节点导致 UI 错乱router.pushUrl跳转时传参params是对象接收页通过router.getParams()获取不能传函数或复杂对象只支持基础类型和简单 JSON 结构。2.3 配置module.json5注册页面与权限修改src/main/module.json5确保abilities数组中包含该页面并添加必要权限{ module: { abilities: [ { name: MainAbility, srcEntry: ./ets/MainAbility.ets, launchType: standard, orientation: unspecified, exported: true, skills: [ { actions: [action.system.home], entities: [entity.system.default] } ] }, { name: MusicListPage, srcEntry: ./ets/pages/MusicListPage.ets, launchType: standard } ], requestPermissions: [ { name: ohos.permission.READ_MEDIA, reason: 用于读取本地音乐文件, usedScene: { abilities: [MainAbility], when: always } }, { name: ohos.permission.INTERNET, reason: 用于请求在线音乐资源, usedScene: { abilities: [MainAbility], when: inuse } } ] } }参数说明READ_MEDIA权限替代了旧版READ_EXTERNAL_STORAGE是 HarmonyOS 4 推荐的媒体读取权限usedScene.when: inuse表示仅在使用网络功能时动态申请比always更符合隐私合规要求skills中的action.system.home是启动首页的标识缺了会导致应用无法从桌面图标启动。3. 实现后台音频服务ServiceExtensionAbility AudioPlayer 的双线程协作3.1 创建 ServiceExtensionAbility 类并注册到 module.json5新建src/main/ets/service/AudioService.ets// src/main/ets/service/AudioService.ets import audio from ohos.multimedia.audio; import common from ohos.app.ability.common; import hilog from ohos.hilog; Extend(common.ServiceExtensionAbility) export class AudioService extends common.ServiceExtensionAbility { private audioPlayer: audio.AudioPlayer | null null; private currentMusicId: string ; onCreate(want: common.Want): void { hilog.info(0x0001, AudioService, onCreate called); this.initAudioPlayer(); } onDestroy(): void { hilog.info(0x0001, AudioService, onDestroy called); this.releasePlayer(); } onCommand(want: common.Want, startId: number): void { const action want.parameters?.action as string; const musicId want.parameters?.musicId as string; switch (action) { case play: this.playMusic(musicId); break; case pause: this.pauseMusic(); break; case stop: this.stopMusic(); break; } } private initAudioPlayer(): void { if (this.audioPlayer) return; this.audioPlayer new audio.AudioPlayer(); this.audioPlayer.on(stateChange, (state: audio.PlayerState) { hilog.info(0x0001, AudioService, Player state: ${state}); // 可在此广播状态变更给前台页面 }); } private playMusic(musicId: string): void { if (!this.audioPlayer) return; this.currentMusicId musicId; // 模拟加载 URL实际应从网络或本地路径获取 const mediaUri https://example.com/music/${musicId}.mp3; this.audioPlayer.reset(); this.audioPlayer.src mediaUri; this.audioPlayer.prepareAsync().then(() { this.audioPlayer.start(); hilog.info(0x0001, AudioService, Started playing ${musicId}); }).catch((err) { hilog.error(0x0001, AudioService, Prepare failed: ${err.message}); }); } private pauseMusic(): void { this.audioPlayer?.pause(); } private stopMusic(): void { this.audioPlayer?.stop(); } private releasePlayer(): void { this.audioPlayer?.release(); this.audioPlayer null; } }逻辑说明Extend(common.ServiceExtensionAbility)是继承 ServiceExtensionAbility 的正确写法不能用extends关键字直接继承类ArkTS 不支持传统类继承onCommand是接收前台命令的入口want.parameters是跨进程传递的数据载体只支持 JSON 序列化类型因此musicId必须是字符串或数字prepareAsync()是异步准备方法必须调用.then()处理成功.catch()捕获失败否则播放失败无提示hilog日志级别0x0001是 INFO调试时可用hilog -p 0x0001过滤查看。3.2 在 module.json5 中注册 ServiceExtensionAbility在src/main/module.json5的module.abilities数组末尾追加{ name: AudioService, srcEntry: ./ets/service/AudioService.ets, type: service, exported: true, backgroundModes: [dataTransfer, audioPlayback] }参数说明type: service表明这是 Service 类型能力backgroundModes: [audioPlayback]是关键缺了此项App 切后台后音频会立即中断exported: true允许其他应用如系统音乐控制中心绑定该服务但本项目仅本应用内使用可设为false以提升安全性。3.3 前台页面调用服务startAbility 与参数传递在MusicListPage.ets的onClick回调中替换跳转逻辑为启动服务// 替换原 router.pushUrl(...) 部分 .onClick(() { const want { bundleName: com.example.hmonmusic, abilityName: AudioService, parameters: { action: play, musicId: item.id } }; try { context.startAbility(want); // 同时跳转播放页保持 UI 响应 router.pushUrl({ url: pages/PlayerPage, params: { musicId: item.id } }); } catch (err) { hilog.error(0x0001, MusicListPage, Start service failed: ${err.message}); } });逻辑说明context.startAbility(want)是启动 Service 的标准方式bundleName必须与build-profile.json5中app.bundleName一致parameters中的action和musicId会透传到AudioService.onCommand()的want.parameters必须用try/catch包裹否则服务未注册或权限缺失时会静默失败UI 无反馈。4. 避坑鸿蒙云音乐开发中 4 个高频翻车点与硬核解法4.1 现象点击播放按钮后log 显示Prepare failed: Invalid URI原因audioPlayer.src设置的 URL 不符合鸿蒙媒体框架要求。常见错误包括使用file://协议但路径未通过ohos.file.fs.openSync()转为fd://使用https://但服务器未配置 CORS或返回非 200 响应URL 中含中文或特殊字符未encodeURIComponent()。解决优先使用fd://方式加载本地文件import fs from ohos.file.fs; const fd fs.openSync(/data/storage/el2/base/haps/entry/files/music.mp3, fs.OpenMode.Read); this.audioPlayer.src fd://${fd};若用网络地址先用ohos.net.http预检const httpRequest http.createHttp(); httpRequest.request(https://example.com/test.mp3, { method: HEAD }) .then((res) { if (res.responseCode 200) this.audioPlayer.src https://...; });4.2 现象App 切后台后音频停止但日志显示Player state: playing原因module.json5中AudioService的backgroundModes缺失audioPlayback或设备未开启「后台活动」权限。解决检查module.json5配置是否完整手动进入设置 → 应用管理 → 本应用 → 后台活动 → 开启「允许后台活动」真机测试必须用 HarmonyOS 4.0 设备模拟器不支持backgroundModes。4.3 现象深色模式下自定义歌词滚动组件背景仍是白色原因Builder函数或Component内部未监听AppTheme变化或Styles定义未使用Resource引用主题色。解决在组件顶层用Watch监听主题State theme: Theme AppTheme.getTheme(); Watch(themeChange) themeChange() { console.info(Theme changed to:, this.theme); }所有颜色值改用Resource.backgroundColor($r(app.color.bg_color)) // 在 resources/base/color.json5 中定义resources/base/color.json5示例{ color: [ { name: bg_color, value: #ffffff }, { name: bg_color_dark, value: #1a1a1a } ] }4.4 现象搜索框输入文字后列表未实时刷新需手动下拉才更新原因State变量被ForEach渲染时其引用未变化如直接this.searchResult filteredListArkTS 无法触发重绘。解决使用Builder封装列表项确保每次渲染都生成新实例或强制更新State引用this.searchResult [...filteredList]; // 浅拷贝触发响应 // 或 this.searchResult JSON.parse(JSON.stringify(filteredList)); // 深拷贝小数据量可用更优解用ObservedObjectLink管理搜索结果对象但需重构数据模型。5. 主题切换与状态同步让深色/浅色模式真正贯穿全链路5.1 在App.ets中统一管理主题状态新建src/main/ets/App.ets若不存在// src/main/ets/App.ets import app from ohos.app.ability.appManager; import { AppTheme } from ohos.app.ability.common; Entry Component struct App { State currentTheme: light | dark light; aboutToAppear() { // 读取系统主题偏好 const systemTheme app.getSystemTheme(); this.currentTheme systemTheme AppTheme.Dark ? dark : light; } build() { // 此处不写 UI仅作为状态容器 } }注意App.ets是整个应用的根组件aboutToAppear在应用启动时执行一次currentTheme可通过Provide向子组件注入。5.2 使用Provide/Consume实现跨页面主题透传在MusicListPage.ets顶部添加Consume(appTheme) appTheme: light | dark; build() { Column({ space: 12 }) { // ...原有代码 } .backgroundColor(this.appTheme dark ? $r(app.color.bg_color_dark) : $r(app.color.bg_color)) }并在src/main/ets/pages/PlayerPage.ets中同样Consume确保所有页面共享同一主题源。5.3 动态切换主题并持久化用户选择新增src/main/ets/utils/ThemeManager.ets// src/main/ets/utils/ThemeManager.ets import preferences from ohos.app.ability.preferences; import { BusinessError } from ohos.base; export class ThemeManager { private static readonly PREF_NAME theme_prefs; private static readonly KEY_THEME selected_theme; static async setTheme(theme: light | dark): Promisevoid { try { const pref await preferences.getPreferences(ThemeManager.PREF_NAME); await pref.putSync(ThemeManager.KEY_THEME, theme); await pref.flush(); } catch (err) { console.error(Save theme failed:, err); } } static async getTheme(): Promiselight | dark { try { const pref await preferences.getPreferences(ThemeManager.PREF_NAME); const saved pref.getSync(ThemeManager.KEY_THEME, system) as string; return saved dark ? dark : light; } catch (err) { return light; } } }在设置页如SettingsPage.ets中调用// 切换按钮 onClick .onClick(async () { const newTheme this.appTheme light ? dark : light; await ThemeManager.setTheme(newTheme); // 触发全局刷新需配合 Provide 更新 this.appTheme newTheme; })逻辑说明preferences是鸿蒙推荐的轻量级键值存储比ohos.data.preferences更简洁putSyncflush()确保写入立即生效避免异步延迟用户手动切换主题后getTheme()返回自定义值覆盖系统默认实现「用户选择优先」。6. 验证与进阶用真机抓包看音频流、用 HiLog 追踪生命周期、用 DevEco Profiler 查内存泄漏6.1 用 HiLog 验证 Service 生命周期是否完整在AudioService.ets的onCreate、onDestroy、onCommand中添加日志onCreate(want: common.Want): void { hilog.info(0x0001, AudioService, onCreate: ${JSON.stringify(want)}); // ... } onDestroy(): void { hilog.info(0x0001, AudioService, onDestroy: service stopped); } onCommand(want: common.Want, startId: number): void { hilog.info(0x0001, AudioService, onCommand: ${want.parameters?.action}, id${want.parameters?.musicId}); }然后在终端执行hilog -p 0x0001 -t 1000 | grep AudioService观察输出是否包含onCreate→onCommand: play→onCommand: pause→onDestroy全流程。若缺onDestroy说明服务未被正确停止可能造成内存泄漏。6.2 用 DevEco Profiler 检测音频播放内存占用运行 App 至播放状态点击 DevEco Studio 右上角Profiler→ 选择当前设备 → 点击Memory标签页点击Record播放 3 分钟音乐期间多次暂停/继续停止录制查看Heap Dump重点检查AudioPlayer实例是否随每次play增加应复用单例若发现AudioPlayer对象数持续增长说明reset()或release()调用缺失需回查playMusic()和onDestroy()。6.3 用 Wireshark 抓包验证「云」部分是否走 HTTPS因鸿蒙限制真机无法直接抓 App 流量但可通过以下方式间接验证在AudioService.playMusic()中将mediaUri改为一个可控的测试域名如https://httpbin.org/delay/2启动 Wireshark过滤http.host contains httpbin.org触发播放确认捕获到GET /delay/2请求且响应状态为200若无流量检查module.json5中INTERNET权限是否生效设置 → 应用管理 → 本应用 → 权限 → 确认已开启。6.4 一个我坚持用的「后悔药」技巧在onDestroy中强制释放所有资源即使文档说AudioPlayer.release()会自动清理我在每个ServiceExtensionAbility的onDestroy里仍加一层保险onDestroy(): void { hilog.info(0x0001, AudioService, onDestroy: releasing resources); this.releasePlayer(); // 原有逻辑 // 额外清理 if (this.audioPlayer) { this.audioPlayer.off(stateChange); // 移除事件监听防内存泄漏 this.audioPlayer null; } // 清理定时器如有 if (this.updateTimer) { clearInterval(this.updateTimer); this.updateTimer undefined; } }这招救过我三次一次是stateChange监听器未注销导致服务重启后重复触发一次是setInterval未清除引发 CPU 持续 15%还有一次是fd未关闭导致下次openSync报EMFILE。鸿蒙的资源回收不如 Node.js 彻底手动归零永远比依赖 GC 更可靠。希望帮到你。本文还有配套的精品资源点击获取
