尧图网页设计 
简介这是一款面向Android开发初学者的实战型音乐播放器项目专为课设实践、移动应用开发入门及UIService综合训练设计。资源完整实现音乐列表展示、本地音频播放、后台服务控制等核心功能涵盖Activity生命周期管理、ListView数据绑定、SharedPreferences轻量存储及MusicPlayer封装等关键知识点助小白快速掌握安卓基础开发全流程。压缩包共1040个文件主体为246个XML布局与样式文件、283个Flat资源、236个JSON配置及9个Java源码辅以MP3示例音频与APK可运行包整体大小216.83MB结构清晰、模块分明便于逐层理解与调试。目前已有9215人学习下载配套源码注释详尽包含完整项目目录、可直接导入Android Studio运行的工程结构以及典型音乐播放逻辑的分步实现范例是夯实安卓四大组件与多媒体开发能力的理想实践素材。1. 项目概述与环境准备1.1 为什么选择音乐播放器作为练手项目学Android开发第一个项目选什么一直是个让人纠结的问题。我见过太多人一上来就抄一个电商App结果布局套了十几层网络请求、数据库、状态管理全挤在一起两个星期后代码自己都看不懂了直接劝退。而音乐播放器这个项目功能边界非常清晰扫描本地音乐文件列表展示点击播放就这三个事。恰恰是这三个事把Android开发最核心的四块基本功全串起来了界面布局、列表展示、运行时权限、多媒体框架。换句话说你做完这个项目等于是把Android开发的地基打了一遍。而且音乐播放器不需要联网不需要后端不涉及账号体系全部逻辑都能在本地跑通出错也容易排查。对于刚接触Android Studio的新手来说把这样一个完整流程走通获得的成就感和对Android组件运行机制的理解远比照着教程抄一个大型项目要扎实得多。我在带新人入门时几乎都会推荐从音乐播放器起步。道理很简单RecyclerView是你以后所有列表页面的基础MediaPlayer帮你理解Android多媒体体系的运作方式动态权限申请则是所有需要访问用户数据的App绕不开的关卡。这三个知识点放到简历里可能不算亮点但放到你的第一行代码里那就是实打实的能力积累。1.2 开发环境搭建与模拟器配置既然项目定位是“小白必看”环境这块就值得多花两分钟说清楚因为很多新手的第一个坑不是代码写不对而是Android Studio压根没跑起来。首先是Android Studio的安装。直接去官方开发者站点下载对应你操作系统的版本即可Windows、macOS、Linux都有对应安装包。安装过程本身没什么难度一路下一步就行真正容易出问题的是以下几个点JDK版本新版Android StudioHedgehog之后的版本内置了JBRJetBrains Runtime默认就是配置好的Java 17环境不需要单独安装JDK。如果你装的是老版本或者手动配置过SDK记得检查一下File Project Structure SDK Location里的路径是否正确。很多“项目运行不了”的问题最后查下来都是JDK或者SDK路径指向了错误目录。SDK组件首次启动Android Studio会让你下载SDK组件这里建议把Android 13API 33和Android 14API 34的SDK Platform都装上后面测试不同版本的权限行为要用到。SDK Manager里还可以顺手装好Android SDK Build-Tools和Platform-Tools。模拟器AVD配置在Tools Device Manager里创建虚拟设备建议直接选一个Pixel系列的机型系统镜像下载API 33或34的x86_64版本运行速度会快很多。如果你的电脑没有开启虚拟化支持BIOS里把Intel VT-x或AMD-V打开否则模拟器会提示“Android Virtual Device unavailable”。这正好是热搜词里很多人搜过的问题我身边就有同事折腾了一晚上最后发现是BIOS虚拟化没开。Gradle同步慢首次创建项目时Gradle需要下载大量依赖国内网络环境下载很慢甚至失败这是高频问题。解决方案是在build.gradle项目级的repositories里加上阿里云镜像源或者在gradle-wrapper.properties中把distributionUrl换到国内镜像地址同步速度会快很多。这个操作已经是Android开发者的必修课了。汉化问题Android Studio默认是英文界面很多人想设置成中文。其实在Settings Plugins里搜索“Chinese Language Pack”安装中文语言包并重启即可。不过我个人的建议是刚开始学还是尽量适应英文界面因为网上绝大多数报错信息和解决方案都是英文的如果你连菜单对应什么都对不上后面排查问题会非常吃力。安装配置好之后先别急着写代码。在模拟器里放两首音乐文件后面测试列表展示和播放要用。最快的方法是直接把MP3文件拖拽到模拟器窗口中系统会自动把它拷贝到存储目录也可以用adb push命令推送但拖拽对小白更友好。2. 项目结构与界面搭建2.1 功能需求拆解与文件规划做项目之前一定先想清楚这个播放器到底要做哪些功能用户怎么操作界面长什么样。我习惯用最简单的描述把需求列出来再反推需要几个类、几个布局文件。这个项目的核心需求拆解下来就三条展示打开App后能看到手机里所有音乐文件每一条显示歌曲名和歌手。点击播放点击某个音乐条目开始播放这首音乐。状态反馈再次点击同一首音乐能够暂停点击另一首切换到新音乐。正在播放的条目用高亮或图标标记出来让用户知道当前播的是哪一首。基于这个需求整个项目的文件规划就非常清晰了MusicBean.java音乐实体类封装歌曲名、歌手、路径、时长等数据。MusicUtils.java工具类负责从系统媒体库扫描并返回音乐列表。MusicAdapter.java列表适配器负责把数据列表绑定到RecyclerView的每一个条目上。MainActivity.java主界面负责权限申请、加载数据、绑定适配器、处理播放逻辑。activity_main.xml主布局包含一个RecyclerView列表。item_music.xml单个音乐条目的布局左右结构左侧显示歌曲信息右侧可以放一个播放状态图标。对于新手我强烈建议不要一上来就引入MVVM、LiveData这些架构组件。这个阶段的核心目标是理解Android的基本运作流程把最基础的一套东西跑通。等你对Activity生命周期、Adapter绑定、MediaPlayer状态切换这些都有体感了再去学习ViewModel、Flow这些进阶工具你会非常深刻地理解它们到底解决了什么问题。反之如果你一开始就套一堆框架出了问题你连报错日志都看不懂是哪一层抛出来的。2.2 布局文件编写与细节处理主界面的布局我选择用LinearLayout垂直包裹一个RecyclerView逻辑简单、代码量少最适合新手理解。如果你想让界面更好看可以把外层换成DrawerLayout或者CoordinatorLayout但这不是当前项目的重点。activity_main.xml的核心结构如下?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightmatch_parent android:orientationvertical androidx.recyclerview.widget.RecyclerView android:idid/rv_music_list android:layout_widthmatch_parent android:layout_heightmatch_parent android:dividernull android:padding8dp / /LinearLayout布局本身没什么花头关键是理解RecyclerView的定位它是Android官方提供的列表组件接管了“滚动”“复用”“布局”这些脏活累活。你只需要告诉它三件事——数据是什么Adapter、每条长什么样item布局、怎么排列LayoutManager它就能高效地把列表渲染出来。如果你想加一个底部播放控制栏只需要在这段代码上面再叠一个LinearLayout里面放上播放/暂停按钮和当前歌曲名即可。这个扩展后面要讲先留个悬念。然后是item_music.xml单个音乐条目的布局?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightwrap_content android:orientationhorizontal android:gravitycenter_vertical android:padding12dp LinearLayout android:layout_width0dp android:layout_heightwrap_content android:layout_weight1 android:orientationvertical TextView android:idid/tv_name android:layout_widthmatch_parent android:layout_heightwrap_content android:text歌曲名称 android:textSize16sp android:textColor#333333 android:maxLines1 android:ellipsizeend / TextView android:idid/tv_artist android:layout_widthmatch_parent android:layout_heightwrap_content android:layout_marginTop4dp android:text未知歌手 android:textSize13sp android:textColor#999999 android:maxLines1 android:ellipsizeend / /LinearLayout TextView android:idid/tv_duration android:layout_widthwrap_content android:layout_heightwrap_content android:layout_marginLeft8dp android:text03:30 android:textSize13sp android:textColor#999999 / /LinearLayout这里有几个细节值得说道说道。权重布局layout_weight是Android线性布局最常用的技巧左边的信息区域宽度设为0dp加上weight1会在父容器中占据所有剩余空间这样右边的时间文本就会被顶到最右侧。maxLines和ellipsize控制歌曲名最多显示一行超出部分用省略号截断保证长歌名不会撑爆布局。这些都是实际开发中高频使用的属性现在打好基础后面写任何列表页面都用得上。3. 核心功能实现从数据到播放3.1 扫描本地音乐ContentResolver与MediaStoreAndroid系统把多媒体文件的元数据统一存放在一个叫MediaStore的媒体数据库中。App通过ContentResolver去查询这个数据库就能拿到设备上所有音频文件的信息这比直接遍历文件目录要可靠得多。因为你不需要自己处理各种文件路径、各种格式兼容性系统都已经帮你管好了。来看MusicUtils.java的完整实现public class MusicUtils { public static ListMusicBean getMusicList(Context context) { ListMusicBean list new ArrayList(); ContentResolver resolver context.getContentResolver(); Uri uri MediaStore.Audio.Media.EXTERNAL_CONTENT_URI; String[] projection { MediaStore.Audio.Media.TITLE, MediaStore.Audio.Media.ARTIST, MediaStore.Audio.Media.DATA, MediaStore.Audio.Media.DURATION, MediaStore.Audio.Media.SIZE }; Cursor cursor null; try { cursor resolver.query(uri, projection, null, null, null); if (cursor ! null) { while (cursor.moveToNext()) { String name cursor.getString(0); String artist cursor.getString(1); String path cursor.getString(2); long duration cursor.getLong(3); long size cursor.getLong(4); // 过滤掉超短音频和小于1MB的文件 if (duration 0 size 1024 * 1024) { list.add(new MusicBean(name, artist, path, duration, size)); } } } } catch (Exception e) { e.printStackTrace(); } finally { if (cursor ! null) { cursor.close(); } } return list; } public static String formatDuration(long duration) { int totalSeconds (int) (duration / 1000); int minutes totalSeconds / 60; int seconds totalSeconds % 60; return String.format(%02d:%02d, minutes, seconds); } }代码不复杂但我重点解释两个容易踩坑的地方。第一是Cursor游标必须要关闭。Cursor是查询结果集的游标对象它持有一块内存资源用完之后不调用close()在大量查询场景下会引发内存泄漏。很多人写代码时图省事最后在LeakCanary里看到一堆内存泄漏报告就是这个原因。第二是过滤条件。为什么我要加duration 0 size 1024 * 1024因为MediaStore会把系统通知音、闹钟铃声、录音片段也收录进去。如果不加过滤你播放器列表里会莫名出现一堆一秒不到的提示音体验非常糟糕。这里的判断标准没有绝对规定你可以根据自己设备上的实际情况调整阈值。1MB以上、时长非零是我总结出来比较稳的组合既能过滤掉系统提示音又能保留正常的MP3文件。当然严谨的做法还可以加上文件名后缀的判断但为了代码简洁过滤条件做到这个程度对新手项目已经足够。对应地MusicBean.java是一个标准的数据实体类字段就五个歌曲名、歌手、文件路径、时长、文件大小提供构造方法、getter和setter。这里就不贴完整代码了你自己写一遍就是最好的练习。3.2 列表展示RecyclerView与Adapter数据拿到之后下一步就是把它们显示到界面上。这里需要三个东西配合LayoutManager决定列表的排列方式、Adapter决定数据怎么和item布局绑定、ViewHolder防止重复查找View的优化手段。MusicAdapter.java完整实现如下public class MusicAdapter extends RecyclerView.AdapterMusicAdapter.ViewHolder { private ListMusicBean list; private Context context; private OnItemClickListener listener; public interface OnItemClickListener { void onItemClick(int position); } public void setOnItemClickListener(OnItemClickListener listener) { this.listener listener; } public MusicAdapter(ListMusicBean list, Context context) { this.list list; this.context context; } NonNull Override public ViewHolder onCreateViewHolder(NonNull ViewGroup parent, int viewType) { View view LayoutInflater.from(context).inflate(R.layout.item_music, parent, false); return new ViewHolder(view); } Override public void onBindViewHolder(NonNull ViewHolder holder, int position) { MusicBean bean list.get(position); holder.tvName.setText(bean.getName()); holder.tvArtist.setText(bean.getArtist()); holder.tvDuration.setText(MusicUtils.formatDuration(bean.getDuration())); holder.itemView.setOnClickListener(v - { if (listener ! null) { listener.onItemClick(holder.getAdapterPosition()); } }); } Override public int getItemCount() { return list.size(); } public static class ViewHolder extends RecyclerView.ViewHolder { TextView tvName; TextView tvArtist; TextView tvDuration; public ViewHolder(NonNull View itemView) { super(itemView); tvName itemView.findViewById(R.id.tv_name); tvArtist itemView.findViewById(R.id.tv_artist); tvDuration itemView.findViewById(R.id.tv_duration); } } }很多新手第一次接触Adapter会被三个方法搞晕onCreateViewHolder、onBindViewHolder、getItemCount。我打一个比方帮助理解RecyclerView是一个流水线工厂getItemCount告诉工厂一共有多少件商品要生产onCreateViewHolder相当于生产出一个个空盒子onBindViewHolder则是把具体商品放进空盒子并贴上标签。onCreateViewHolder不会每显示一条就调用一次当某个条目滚出屏幕时它的ViewHolder会被回收复用这就是RecyclerView性能好的根本原因。在onBindViewHolder里我要特别强调一个细节点击事件的回调参数不要直接用外部传入的position而要用holder.getAdapterPosition()。这是因为当列表进行增删操作或局部刷新时position可能已经过期导致点击错位。用getAdapterPosition()拿到的是当前最新的位置。这是很多老开发都会中招的隐藏Bug新手一开始就养成这个习惯能省掉后面不少排查时间。3.3 播放控制MediaPlayer完整流程MediaPlayer是Android原生的多媒体播放器框架。说它简单也简单核心就一个对象几个方法说它复杂也复杂因为它的底层是个状态机不同状态下调用不同方法会触发乱七八糟的异常。对新手来说你只需要记住一个简化版的正常流程创建一个MediaPlayer实例设置数据源调用prepare()进入准备完成状态然后start()开始播放。就这么简单。MainActivity.java里与播放相关的核心代码private MediaPlayer mediaPlayer; private int currentPosition -1; private void playMusic(int position) { try { if (mediaPlayer null) { mediaPlayer new MediaPlayer(); } if (currentPosition position) { // 点击的是同一首切换播放/暂停 if (mediaPlayer.isPlaying()) { mediaPlayer.pause(); } else { mediaPlayer.start(); } } else { // 点击的是不同音乐重置并播放新音乐 mediaPlayer.reset(); mediaPlayer.setDataSource(musicList.get(position).getPath()); mediaPlayer.prepare(); mediaPlayer.start(); currentPosition position; } } catch (IOException e) { e.printStackTrace(); } }这个逻辑我用四个字总结同曲切换异曲更换。当用户连续点击同一首音乐时你需要做的是暂停或继续而不是重新加载否则音乐会从头开始播放体验很生硬。当用户点击不同音乐时必须先调用reset()让MediaPlayer回到初始状态再设置新的数据源。这个reset()就是最容易踩坑的地方——很多人直接setDataSource准备第二首结果抛出IllegalStateException原因就是MediaPlayer还停留在上一个播放状态不允许直接换源。打开MainActivity之后的完整流程是这样先请求存储权限权限通过后调用MusicUtils.getMusicList(this)加载数据设置适配器然后调用一次loadMusicList()。这套流程里有一步非常关键就是权限回调的处理Override public void onRequestPermissionsResult(int requestCode, NonNull String[] permissions, NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode REQUEST_PERMISSION) { if (grantResults.length 0 grantResults[0] PackageManager.PERMISSION_GRANTED) { loadMusicList(); } else { Toast.makeText(this, 需要存储权限才能读取音乐列表, Toast.LENGTH_SHORT).show(); } } }记得在onDestroy里释放MediaPlayer资源Override protected void onDestroy() { super.onDestroy(); if (mediaPlayer ! null) { mediaPlayer.release(); mediaPlayer null; } }release()是把MediaPlayer占用的底层资源音频解码器、硬件资源等彻底释放这个操作必须做。如果你只是让Activity销毁而不管MediaPlayer播放器会继续在后台工作甚至引发AudioFocus冲突使其他App的音乐播放变得断断续续。4. 常见问题排查与进阶扩展4.1 新手最容易踩的五个坑我把这几年看新人做这个项目时频繁翻车的场景做了一张速查表你对照着排查比自己瞎猜效率高得多。问题现象根本原因解决方案列表始终空白没有任何数据存储权限没通过或者未在运行时动态申请检查AndroidManifest中的权限声明和onRequestPermissionsResult回调逻辑点击音乐条目无反应MediaPlayer未正确初始化或未设置点击监听确认mediaPlayer已实例化确认Adapter设置了setOnItemClickListener点击不同歌曲却播了同一首没有调用mediaPlayer.reset()状态残留每次切换数据源前先调用reset()模拟器里没有音乐数据模拟器存储中没有MP3文件拖拽音频文件到模拟器窗口或用adb push推送编译报错找不到R文件布局文件里存在语法错误或资源命名不规范检查XML文件是否有红色报错编译日志会明确给出哪个文件出错除了表里的这些还有一个很隐蔽的问题值得单独拿出来说。prepare()是一个耗时操作它需要从文件系统读取数据、解析音频格式、分配解码器资源整个过程可能在几百毫秒到几秒之间。在这个阶段如果你调用了start()是没有效果的。所以我在MainActivity里用的是同步的prepare()确保前一首音乐加载完成后再启动播放。如果你的音乐文件比较大或者你打算把网络音乐地址塞进来那就要用prepareAsync()配合setOnPreparedListener做异步准备否则会卡主线程。另外一个隐蔽问题是音频焦点Audio Focus。简单来说如果你的App不申请音频焦点即使你在后台播放音乐用户打开抖音时两个App的声音会叠在一起用户会直接卸载你的App。后面做进阶版本时一定要在播放前通过AudioManager.requestAudioFocus请求焦点在暂停或停止时通过abandonAudioFocus释放焦点。这个是专业播放器和练手项目之间的一道分水岭。4.2 Android 13及以上的权限适配这个坑特别值得单独拿出来讲。Android 13API 33开始读取音频文件的权限从原来的READ_EXTERNAL_STORAGE改成了细分权限READ_MEDIA_AUDIO。如果你的项目targetSdkVersion设置成33或更高在Android 13设备上运行时老权限会变得无效导致列表空白。所以开发时你需要做一层判断private boolean hasReadAudioPermission() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { return checkSelfPermission(Manifest.permission.READ_MEDIA_AUDIO) PackageManager.PERMISSION_GRANTED; } else { return checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE) PackageManager.PERMISSION_GRANTED; } }同时在AndroidManifest.xml里声明两个权限uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.READ_MEDIA_AUDIO /这样App在不同Android版本上运行时都会申请到对应版本的音频读取权限。如果你不处理这个差异你在自己的平板上开发测试一切正常发到用户那里Android 13以上的设备全部白屏这个Bug排查起来非常容易让人一头雾水。我在开发实战中遇到过太多次类似的情况结论就是高版本兼容性永远要在写完代码的第一时间做适配千万别拖到上架阶段再改。4.3 功能扩展方向与实用建议把基础版跑通之后这个项目其实是一块很好的“画布”你可以根据自己的兴趣往上面加功能。我按难度递增的顺序推荐几个方向加播放模式。循环播放、随机播放、单曲循环这是音乐播放器最基本的配置。实现上不复杂关键是维护一个播放模式状态在setOnCompletionListener里根据模式决定下一首的逻辑。加底部控制栏。用一个固定在屏幕底部的LinearLayout当前播放时显示歌曲名旁边放一个播放/暂停按钮。这里需要把MediaPlayer的状态同步到UI比如播放时按钮显示暂停图标暂停时按钮显示播放图标。这个小功能会让你对“UI与状态同步”这件事有直观理解也是后面学习ViewModel的绝佳铺垫。加后台播放能力。用Service承载播放逻辑让App退到后台后音乐依然能播放。到了这一步你就开始接触Android四大组件中最复杂的Service体系了。它会连带引入Notification前台通知、PendingIntent、甚至音频焦点处理。能把这条线全部打通你在Android开发里已经不再是纯小白了。加网络音乐源。把数据源从本地文件换成网络URLMediaPlayer的setDataSource(String url)可以直接接收HTTP链接。这一步会牵扯到网络权限声明、网络状态监听和异步缓冲处理比本地播放要复杂不少但项目的实用性和完成度也会飞跃式提升。我个人在实际操作中的体会是做项目最忌一口气贪多。先把基础版本代码一行一行敲通把MediaPlayer的每次状态切换都在心里过一遍把权限回调的每个分支都走一遍然后再逐步加功能。这个过程比你看十篇教程都管用。还有个小技巧想分享给所有新手开发时打开Android Studio的Logcat面板把日志级别降到Debug运行App时多观察输出的日志信息。Android系统会在MediaPlayer状态切换时输出大量有用的log这些日志是你调试播放问题的最可靠依据比到处查资料高效得多。本文还有配套的精品资源点击获取 Android开发入门实战：从零实现本地音乐播放器
简介这是一款面向Android开发初学者的实战型音乐播放器项目专为课设实践、移动应用开发入门及UIService综合训练设计。资源完整实现音乐列表展示、本地音频播放、后台服务控制等核心功能涵盖Activity生命周期管理、ListView数据绑定、SharedPreferences轻量存储及MusicPlayer封装等关键知识点助小白快速掌握安卓基础开发全流程。压缩包共1040个文件主体为246个XML布局与样式文件、283个Flat资源、236个JSON配置及9个Java源码辅以MP3示例音频与APK可运行包整体大小216.83MB结构清晰、模块分明便于逐层理解与调试。目前已有9215人学习下载配套源码注释详尽包含完整项目目录、可直接导入Android Studio运行的工程结构以及典型音乐播放逻辑的分步实现范例是夯实安卓四大组件与多媒体开发能力的理想实践素材。1. 项目概述与环境准备1.1 为什么选择音乐播放器作为练手项目学Android开发第一个项目选什么一直是个让人纠结的问题。我见过太多人一上来就抄一个电商App结果布局套了十几层网络请求、数据库、状态管理全挤在一起两个星期后代码自己都看不懂了直接劝退。而音乐播放器这个项目功能边界非常清晰扫描本地音乐文件列表展示点击播放就这三个事。恰恰是这三个事把Android开发最核心的四块基本功全串起来了界面布局、列表展示、运行时权限、多媒体框架。换句话说你做完这个项目等于是把Android开发的地基打了一遍。而且音乐播放器不需要联网不需要后端不涉及账号体系全部逻辑都能在本地跑通出错也容易排查。对于刚接触Android Studio的新手来说把这样一个完整流程走通获得的成就感和对Android组件运行机制的理解远比照着教程抄一个大型项目要扎实得多。我在带新人入门时几乎都会推荐从音乐播放器起步。道理很简单RecyclerView是你以后所有列表页面的基础MediaPlayer帮你理解Android多媒体体系的运作方式动态权限申请则是所有需要访问用户数据的App绕不开的关卡。这三个知识点放到简历里可能不算亮点但放到你的第一行代码里那就是实打实的能力积累。1.2 开发环境搭建与模拟器配置既然项目定位是“小白必看”环境这块就值得多花两分钟说清楚因为很多新手的第一个坑不是代码写不对而是Android Studio压根没跑起来。首先是Android Studio的安装。直接去官方开发者站点下载对应你操作系统的版本即可Windows、macOS、Linux都有对应安装包。安装过程本身没什么难度一路下一步就行真正容易出问题的是以下几个点JDK版本新版Android StudioHedgehog之后的版本内置了JBRJetBrains Runtime默认就是配置好的Java 17环境不需要单独安装JDK。如果你装的是老版本或者手动配置过SDK记得检查一下File Project Structure SDK Location里的路径是否正确。很多“项目运行不了”的问题最后查下来都是JDK或者SDK路径指向了错误目录。SDK组件首次启动Android Studio会让你下载SDK组件这里建议把Android 13API 33和Android 14API 34的SDK Platform都装上后面测试不同版本的权限行为要用到。SDK Manager里还可以顺手装好Android SDK Build-Tools和Platform-Tools。模拟器AVD配置在Tools Device Manager里创建虚拟设备建议直接选一个Pixel系列的机型系统镜像下载API 33或34的x86_64版本运行速度会快很多。如果你的电脑没有开启虚拟化支持BIOS里把Intel VT-x或AMD-V打开否则模拟器会提示“Android Virtual Device unavailable”。这正好是热搜词里很多人搜过的问题我身边就有同事折腾了一晚上最后发现是BIOS虚拟化没开。Gradle同步慢首次创建项目时Gradle需要下载大量依赖国内网络环境下载很慢甚至失败这是高频问题。解决方案是在build.gradle项目级的repositories里加上阿里云镜像源或者在gradle-wrapper.properties中把distributionUrl换到国内镜像地址同步速度会快很多。这个操作已经是Android开发者的必修课了。汉化问题Android Studio默认是英文界面很多人想设置成中文。其实在Settings Plugins里搜索“Chinese Language Pack”安装中文语言包并重启即可。不过我个人的建议是刚开始学还是尽量适应英文界面因为网上绝大多数报错信息和解决方案都是英文的如果你连菜单对应什么都对不上后面排查问题会非常吃力。安装配置好之后先别急着写代码。在模拟器里放两首音乐文件后面测试列表展示和播放要用。最快的方法是直接把MP3文件拖拽到模拟器窗口中系统会自动把它拷贝到存储目录也可以用adb push命令推送但拖拽对小白更友好。2. 项目结构与界面搭建2.1 功能需求拆解与文件规划做项目之前一定先想清楚这个播放器到底要做哪些功能用户怎么操作界面长什么样。我习惯用最简单的描述把需求列出来再反推需要几个类、几个布局文件。这个项目的核心需求拆解下来就三条展示打开App后能看到手机里所有音乐文件每一条显示歌曲名和歌手。点击播放点击某个音乐条目开始播放这首音乐。状态反馈再次点击同一首音乐能够暂停点击另一首切换到新音乐。正在播放的条目用高亮或图标标记出来让用户知道当前播的是哪一首。基于这个需求整个项目的文件规划就非常清晰了MusicBean.java音乐实体类封装歌曲名、歌手、路径、时长等数据。MusicUtils.java工具类负责从系统媒体库扫描并返回音乐列表。MusicAdapter.java列表适配器负责把数据列表绑定到RecyclerView的每一个条目上。MainActivity.java主界面负责权限申请、加载数据、绑定适配器、处理播放逻辑。activity_main.xml主布局包含一个RecyclerView列表。item_music.xml单个音乐条目的布局左右结构左侧显示歌曲信息右侧可以放一个播放状态图标。对于新手我强烈建议不要一上来就引入MVVM、LiveData这些架构组件。这个阶段的核心目标是理解Android的基本运作流程把最基础的一套东西跑通。等你对Activity生命周期、Adapter绑定、MediaPlayer状态切换这些都有体感了再去学习ViewModel、Flow这些进阶工具你会非常深刻地理解它们到底解决了什么问题。反之如果你一开始就套一堆框架出了问题你连报错日志都看不懂是哪一层抛出来的。2.2 布局文件编写与细节处理主界面的布局我选择用LinearLayout垂直包裹一个RecyclerView逻辑简单、代码量少最适合新手理解。如果你想让界面更好看可以把外层换成DrawerLayout或者CoordinatorLayout但这不是当前项目的重点。activity_main.xml的核心结构如下?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightmatch_parent android:orientationvertical androidx.recyclerview.widget.RecyclerView android:idid/rv_music_list android:layout_widthmatch_parent android:layout_heightmatch_parent android:dividernull android:padding8dp / /LinearLayout布局本身没什么花头关键是理解RecyclerView的定位它是Android官方提供的列表组件接管了“滚动”“复用”“布局”这些脏活累活。你只需要告诉它三件事——数据是什么Adapter、每条长什么样item布局、怎么排列LayoutManager它就能高效地把列表渲染出来。如果你想加一个底部播放控制栏只需要在这段代码上面再叠一个LinearLayout里面放上播放/暂停按钮和当前歌曲名即可。这个扩展后面要讲先留个悬念。然后是item_music.xml单个音乐条目的布局?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightwrap_content android:orientationhorizontal android:gravitycenter_vertical android:padding12dp LinearLayout android:layout_width0dp android:layout_heightwrap_content android:layout_weight1 android:orientationvertical TextView android:idid/tv_name android:layout_widthmatch_parent android:layout_heightwrap_content android:text歌曲名称 android:textSize16sp android:textColor#333333 android:maxLines1 android:ellipsizeend / TextView android:idid/tv_artist android:layout_widthmatch_parent android:layout_heightwrap_content android:layout_marginTop4dp android:text未知歌手 android:textSize13sp android:textColor#999999 android:maxLines1 android:ellipsizeend / /LinearLayout TextView android:idid/tv_duration android:layout_widthwrap_content android:layout_heightwrap_content android:layout_marginLeft8dp android:text03:30 android:textSize13sp android:textColor#999999 / /LinearLayout这里有几个细节值得说道说道。权重布局layout_weight是Android线性布局最常用的技巧左边的信息区域宽度设为0dp加上weight1会在父容器中占据所有剩余空间这样右边的时间文本就会被顶到最右侧。maxLines和ellipsize控制歌曲名最多显示一行超出部分用省略号截断保证长歌名不会撑爆布局。这些都是实际开发中高频使用的属性现在打好基础后面写任何列表页面都用得上。3. 核心功能实现从数据到播放3.1 扫描本地音乐ContentResolver与MediaStoreAndroid系统把多媒体文件的元数据统一存放在一个叫MediaStore的媒体数据库中。App通过ContentResolver去查询这个数据库就能拿到设备上所有音频文件的信息这比直接遍历文件目录要可靠得多。因为你不需要自己处理各种文件路径、各种格式兼容性系统都已经帮你管好了。来看MusicUtils.java的完整实现public class MusicUtils { public static ListMusicBean getMusicList(Context context) { ListMusicBean list new ArrayList(); ContentResolver resolver context.getContentResolver(); Uri uri MediaStore.Audio.Media.EXTERNAL_CONTENT_URI; String[] projection { MediaStore.Audio.Media.TITLE, MediaStore.Audio.Media.ARTIST, MediaStore.Audio.Media.DATA, MediaStore.Audio.Media.DURATION, MediaStore.Audio.Media.SIZE }; Cursor cursor null; try { cursor resolver.query(uri, projection, null, null, null); if (cursor ! null) { while (cursor.moveToNext()) { String name cursor.getString(0); String artist cursor.getString(1); String path cursor.getString(2); long duration cursor.getLong(3); long size cursor.getLong(4); // 过滤掉超短音频和小于1MB的文件 if (duration 0 size 1024 * 1024) { list.add(new MusicBean(name, artist, path, duration, size)); } } } } catch (Exception e) { e.printStackTrace(); } finally { if (cursor ! null) { cursor.close(); } } return list; } public static String formatDuration(long duration) { int totalSeconds (int) (duration / 1000); int minutes totalSeconds / 60; int seconds totalSeconds % 60; return String.format(%02d:%02d, minutes, seconds); } }代码不复杂但我重点解释两个容易踩坑的地方。第一是Cursor游标必须要关闭。Cursor是查询结果集的游标对象它持有一块内存资源用完之后不调用close()在大量查询场景下会引发内存泄漏。很多人写代码时图省事最后在LeakCanary里看到一堆内存泄漏报告就是这个原因。第二是过滤条件。为什么我要加duration 0 size 1024 * 1024因为MediaStore会把系统通知音、闹钟铃声、录音片段也收录进去。如果不加过滤你播放器列表里会莫名出现一堆一秒不到的提示音体验非常糟糕。这里的判断标准没有绝对规定你可以根据自己设备上的实际情况调整阈值。1MB以上、时长非零是我总结出来比较稳的组合既能过滤掉系统提示音又能保留正常的MP3文件。当然严谨的做法还可以加上文件名后缀的判断但为了代码简洁过滤条件做到这个程度对新手项目已经足够。对应地MusicBean.java是一个标准的数据实体类字段就五个歌曲名、歌手、文件路径、时长、文件大小提供构造方法、getter和setter。这里就不贴完整代码了你自己写一遍就是最好的练习。3.2 列表展示RecyclerView与Adapter数据拿到之后下一步就是把它们显示到界面上。这里需要三个东西配合LayoutManager决定列表的排列方式、Adapter决定数据怎么和item布局绑定、ViewHolder防止重复查找View的优化手段。MusicAdapter.java完整实现如下public class MusicAdapter extends RecyclerView.AdapterMusicAdapter.ViewHolder { private ListMusicBean list; private Context context; private OnItemClickListener listener; public interface OnItemClickListener { void onItemClick(int position); } public void setOnItemClickListener(OnItemClickListener listener) { this.listener listener; } public MusicAdapter(ListMusicBean list, Context context) { this.list list; this.context context; } NonNull Override public ViewHolder onCreateViewHolder(NonNull ViewGroup parent, int viewType) { View view LayoutInflater.from(context).inflate(R.layout.item_music, parent, false); return new ViewHolder(view); } Override public void onBindViewHolder(NonNull ViewHolder holder, int position) { MusicBean bean list.get(position); holder.tvName.setText(bean.getName()); holder.tvArtist.setText(bean.getArtist()); holder.tvDuration.setText(MusicUtils.formatDuration(bean.getDuration())); holder.itemView.setOnClickListener(v - { if (listener ! null) { listener.onItemClick(holder.getAdapterPosition()); } }); } Override public int getItemCount() { return list.size(); } public static class ViewHolder extends RecyclerView.ViewHolder { TextView tvName; TextView tvArtist; TextView tvDuration; public ViewHolder(NonNull View itemView) { super(itemView); tvName itemView.findViewById(R.id.tv_name); tvArtist itemView.findViewById(R.id.tv_artist); tvDuration itemView.findViewById(R.id.tv_duration); } } }很多新手第一次接触Adapter会被三个方法搞晕onCreateViewHolder、onBindViewHolder、getItemCount。我打一个比方帮助理解RecyclerView是一个流水线工厂getItemCount告诉工厂一共有多少件商品要生产onCreateViewHolder相当于生产出一个个空盒子onBindViewHolder则是把具体商品放进空盒子并贴上标签。onCreateViewHolder不会每显示一条就调用一次当某个条目滚出屏幕时它的ViewHolder会被回收复用这就是RecyclerView性能好的根本原因。在onBindViewHolder里我要特别强调一个细节点击事件的回调参数不要直接用外部传入的position而要用holder.getAdapterPosition()。这是因为当列表进行增删操作或局部刷新时position可能已经过期导致点击错位。用getAdapterPosition()拿到的是当前最新的位置。这是很多老开发都会中招的隐藏Bug新手一开始就养成这个习惯能省掉后面不少排查时间。3.3 播放控制MediaPlayer完整流程MediaPlayer是Android原生的多媒体播放器框架。说它简单也简单核心就一个对象几个方法说它复杂也复杂因为它的底层是个状态机不同状态下调用不同方法会触发乱七八糟的异常。对新手来说你只需要记住一个简化版的正常流程创建一个MediaPlayer实例设置数据源调用prepare()进入准备完成状态然后start()开始播放。就这么简单。MainActivity.java里与播放相关的核心代码private MediaPlayer mediaPlayer; private int currentPosition -1; private void playMusic(int position) { try { if (mediaPlayer null) { mediaPlayer new MediaPlayer(); } if (currentPosition position) { // 点击的是同一首切换播放/暂停 if (mediaPlayer.isPlaying()) { mediaPlayer.pause(); } else { mediaPlayer.start(); } } else { // 点击的是不同音乐重置并播放新音乐 mediaPlayer.reset(); mediaPlayer.setDataSource(musicList.get(position).getPath()); mediaPlayer.prepare(); mediaPlayer.start(); currentPosition position; } } catch (IOException e) { e.printStackTrace(); } }这个逻辑我用四个字总结同曲切换异曲更换。当用户连续点击同一首音乐时你需要做的是暂停或继续而不是重新加载否则音乐会从头开始播放体验很生硬。当用户点击不同音乐时必须先调用reset()让MediaPlayer回到初始状态再设置新的数据源。这个reset()就是最容易踩坑的地方——很多人直接setDataSource准备第二首结果抛出IllegalStateException原因就是MediaPlayer还停留在上一个播放状态不允许直接换源。打开MainActivity之后的完整流程是这样先请求存储权限权限通过后调用MusicUtils.getMusicList(this)加载数据设置适配器然后调用一次loadMusicList()。这套流程里有一步非常关键就是权限回调的处理Override public void onRequestPermissionsResult(int requestCode, NonNull String[] permissions, NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode REQUEST_PERMISSION) { if (grantResults.length 0 grantResults[0] PackageManager.PERMISSION_GRANTED) { loadMusicList(); } else { Toast.makeText(this, 需要存储权限才能读取音乐列表, Toast.LENGTH_SHORT).show(); } } }记得在onDestroy里释放MediaPlayer资源Override protected void onDestroy() { super.onDestroy(); if (mediaPlayer ! null) { mediaPlayer.release(); mediaPlayer null; } }release()是把MediaPlayer占用的底层资源音频解码器、硬件资源等彻底释放这个操作必须做。如果你只是让Activity销毁而不管MediaPlayer播放器会继续在后台工作甚至引发AudioFocus冲突使其他App的音乐播放变得断断续续。4. 常见问题排查与进阶扩展4.1 新手最容易踩的五个坑我把这几年看新人做这个项目时频繁翻车的场景做了一张速查表你对照着排查比自己瞎猜效率高得多。问题现象根本原因解决方案列表始终空白没有任何数据存储权限没通过或者未在运行时动态申请检查AndroidManifest中的权限声明和onRequestPermissionsResult回调逻辑点击音乐条目无反应MediaPlayer未正确初始化或未设置点击监听确认mediaPlayer已实例化确认Adapter设置了setOnItemClickListener点击不同歌曲却播了同一首没有调用mediaPlayer.reset()状态残留每次切换数据源前先调用reset()模拟器里没有音乐数据模拟器存储中没有MP3文件拖拽音频文件到模拟器窗口或用adb push推送编译报错找不到R文件布局文件里存在语法错误或资源命名不规范检查XML文件是否有红色报错编译日志会明确给出哪个文件出错除了表里的这些还有一个很隐蔽的问题值得单独拿出来说。prepare()是一个耗时操作它需要从文件系统读取数据、解析音频格式、分配解码器资源整个过程可能在几百毫秒到几秒之间。在这个阶段如果你调用了start()是没有效果的。所以我在MainActivity里用的是同步的prepare()确保前一首音乐加载完成后再启动播放。如果你的音乐文件比较大或者你打算把网络音乐地址塞进来那就要用prepareAsync()配合setOnPreparedListener做异步准备否则会卡主线程。另外一个隐蔽问题是音频焦点Audio Focus。简单来说如果你的App不申请音频焦点即使你在后台播放音乐用户打开抖音时两个App的声音会叠在一起用户会直接卸载你的App。后面做进阶版本时一定要在播放前通过AudioManager.requestAudioFocus请求焦点在暂停或停止时通过abandonAudioFocus释放焦点。这个是专业播放器和练手项目之间的一道分水岭。4.2 Android 13及以上的权限适配这个坑特别值得单独拿出来讲。Android 13API 33开始读取音频文件的权限从原来的READ_EXTERNAL_STORAGE改成了细分权限READ_MEDIA_AUDIO。如果你的项目targetSdkVersion设置成33或更高在Android 13设备上运行时老权限会变得无效导致列表空白。所以开发时你需要做一层判断private boolean hasReadAudioPermission() { if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { return checkSelfPermission(Manifest.permission.READ_MEDIA_AUDIO) PackageManager.PERMISSION_GRANTED; } else { return checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE) PackageManager.PERMISSION_GRANTED; } }同时在AndroidManifest.xml里声明两个权限uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.READ_MEDIA_AUDIO /这样App在不同Android版本上运行时都会申请到对应版本的音频读取权限。如果你不处理这个差异你在自己的平板上开发测试一切正常发到用户那里Android 13以上的设备全部白屏这个Bug排查起来非常容易让人一头雾水。我在开发实战中遇到过太多次类似的情况结论就是高版本兼容性永远要在写完代码的第一时间做适配千万别拖到上架阶段再改。4.3 功能扩展方向与实用建议把基础版跑通之后这个项目其实是一块很好的“画布”你可以根据自己的兴趣往上面加功能。我按难度递增的顺序推荐几个方向加播放模式。循环播放、随机播放、单曲循环这是音乐播放器最基本的配置。实现上不复杂关键是维护一个播放模式状态在setOnCompletionListener里根据模式决定下一首的逻辑。加底部控制栏。用一个固定在屏幕底部的LinearLayout当前播放时显示歌曲名旁边放一个播放/暂停按钮。这里需要把MediaPlayer的状态同步到UI比如播放时按钮显示暂停图标暂停时按钮显示播放图标。这个小功能会让你对“UI与状态同步”这件事有直观理解也是后面学习ViewModel的绝佳铺垫。加后台播放能力。用Service承载播放逻辑让App退到后台后音乐依然能播放。到了这一步你就开始接触Android四大组件中最复杂的Service体系了。它会连带引入Notification前台通知、PendingIntent、甚至音频焦点处理。能把这条线全部打通你在Android开发里已经不再是纯小白了。加网络音乐源。把数据源从本地文件换成网络URLMediaPlayer的setDataSource(String url)可以直接接收HTTP链接。这一步会牵扯到网络权限声明、网络状态监听和异步缓冲处理比本地播放要复杂不少但项目的实用性和完成度也会飞跃式提升。我个人在实际操作中的体会是做项目最忌一口气贪多。先把基础版本代码一行一行敲通把MediaPlayer的每次状态切换都在心里过一遍把权限回调的每个分支都走一遍然后再逐步加功能。这个过程比你看十篇教程都管用。还有个小技巧想分享给所有新手开发时打开Android Studio的Logcat面板把日志级别降到Debug运行App时多观察输出的日志信息。Android系统会在MediaPlayer状态切换时输出大量有用的log这些日志是你调试播放问题的最可靠依据比到处查资料高效得多。本文还有配套的精品资源点击获取