做安卓开发这些年，要说哪个问题排查起来最让容易让人头大，音频问题绝对排前三。不是代码难写，而是你写对了代码，声音却可能从别的地方跑出来，或者压根没声。我印象最深的一次，客户报了一个“蓝牙耳机连上后App声音外放”的bug，我翻了两天代码，最后发现是设备的audio_policy_configuration.xml里路由策略和产品定义不符，改一行配置就解决了。从那时候起我就明白，搞安卓音视频，必须得把音频配置文件这套东西吃透。
这篇文章不打算给你念源码注释，而是从实际项目出发，把 Android 音频配置文件的核心逻辑和实操细节拆开揉碎。系统开发者可以在这里找到修改audio_policy的具体方法，应用层开发者也能搞清楚AudioAttributes、音频焦点、甚至 FileProvider 与音频文件访问之间那些绕不开的关系。无论你是正在适配新设备、调音频路由，还是被音频焦点搞得焦头烂额，这篇文章都值得存一份。
1. Android音频体系与配置文件定位
1.1 音频管道的完整链路：从代码到喇叭
在聊配置之前，得先把音频数据从应用走到硬件这条链路捋清楚。一次最简单的音乐播放，大致会经过四个层级：
- 应用层：通过
MediaPlayer、SoundPool或者AudioTrack创建音频流，同时携带一组“音频属性”（usage、contentType）。 - AudioFlinger：系统的音频混音服务，把所有应用的音频流混在一起，负责处理采样率转换、音效插入等。
- AudioPolicyManager：音频路由决策者，根据应用请求的 audo attributes、当前设备状态（耳机、蓝牙、扬声器）以及系统配置文件里的策略，决定音频走哪个输出设备。
- Audio HAL 层：直接与声卡、Codec、功放打交道，把混音后的 PCM 数据送到指定硬件。
在这个链路里，应用层决定“我想播放什么”，而把“声音从哪里出来”这个关键决策交给了 AudioPolicyManager。这个决策依据，就来自我们常说的音频策略配置文件。
如果你把整个体系想成一栋楼的供水系统：应用是各个房间的水龙头，AudioFlinger 是水泵，AudioPolicyManager 是阀门路由，配置文件就是那张“哪个水龙头接哪根管道”的设计图。设计图画错了，别说水压不稳，水都可能流到别人家去。
1.2 配置文件在系统中的使命
Android 音频配置文件并不是单独一个文件，而是一套组合，核心包括：
audio_policy_configuration.xml：主策略文件，定义音频设备、混音端口、路由关系。audio_policy_volumes.xml：音量曲线配置，定义不同音频流类型的音量级数与衰减值。surround_sound_configuration_*.xml：环绕声设备相关配置。audio_effects.xml：音频效果链配置，比如均衡器、环绕声、降噪等。
整套配置的核心角色就是audio_policy_configuration.xml。它告诉系统：系统上有哪些物理音频设备、哪些可输出混音数据的端口、端口与设备之间怎么连接、默认情况下优先使用哪个设备。
我从实际开发中得到的经验是：遇到设备上“某个音频场景始终不对”的情况，先别急着调应用代码，花二十分钟把dumpsys audio的输出和这个配置文件对照着看一遍，定位效率要高得多。很多所谓“App的问题”，最后都被证明是系统配置和产品预期不一致导致的。
2. 核心配置文件 audio_policy_configuration.xml 深度拆解
2.1 文件位置与加载机制
在 AOSP 源码中，主策略文件通常位于：
frameworks/av/services/audiopolicy/config/audio_policy_configuration.xml- 或特定硬件平台目录下，如
device/<vendor>/<board>/audio/audio_policy_configuration.xml
编译后，它会被打包进系统镜像，目标路径是/system/etc/audio_policy_configuration.xml，vendor 分区也有自己的/vendor/etc/audio_policy_configuration.xml。设备启动时，AudioPolicyManager 会按优先级加载这些文件，生成全局的音频路由策略对象。
有一个很多新手容易忽略的点：如果设备启用了 VTS（Vendor Test Suite）音频测试，配置文件必须通过audio_policy_configuration_V7_0这类 XML Schema 校验。我在工作中就见到过，因为某个新增设备的 name 标签不合法，导致音频服务反复重启，整机卡在开机动画。
建议任何修改操作之前，先把原文件备份一份，并利用系统自带的check_policy工具或者 Android 源码下的测试脚本做一遍语法校验，别等烧录进设备才后悔。
2.2 核心标签逐个拆解
下面这段配置是我从一台量产平板上导出的精简版，足够说明核心结构：
<audioPolicyConfiguration version="1.0"> <globalConfiguration speaker_drc_enabled="true"/> <modules> <module name="primary" halVersion="3.0"> <attachedDevices> <item>Speaker</item> <item>Built-In Mic</item> </attachedDevices> <defaultOutputDevice>Speaker</defaultOutputDevice> <mixPorts> <mixPort name="primary output" role="source"> <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" samplingRates="48000" channelMasks="AUDIO_CHANNEL_OUT_STEREO"/> </mixPort> <mixPort name="primary input" role="sink"> <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" samplingRates="48000" channelMasks="AUDIO_CHANNEL_IN_MONO"/> </mixPort> </mixPorts> <devicePorts> <devicePort tagName="Speaker" type="AUDIO_DEVICE_OUT_SPEAKER" role="sink"> <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" samplingRates="48000" channelMasks="AUDIO_CHANNEL_OUT_STEREO"/> </devicePort> <devicePort tagName="Built-In Mic" type="AUDIO_DEVICE_IN_BUILTIN_MIC" role="source"> <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" samplingRates="48000" channelMasks="AUDIO_CHANNEL_IN_MONO"/> </devicePort> </devicePorts> <routes> <route type="mix" sink="Speaker" sources="primary output"/> <route type="mix" sink="primary input" sources="Built-In Mic"/> </routes> </module> </modules> </audioPolicyConfiguration>我来逐个解释这些标签在系统中真正起的作用：
- module：一个音频硬件抽象单元，
name必须是 HAL 库注册的名字，常见的是primary，还有a2dp、usb、r_submix等。主模块加载失败，系统可能直接没有音频输出。 - attachedDevices：系统启动时“默认连接”的物理设备列表。这里写的是内部设备，外部设备（蓝牙、USB耳机）一般由 HAL 在设备连接时动态上报。
- defaultOutputDevice：没有任何应用指定设备偏好时，音频流默认去的设备。这个字段非常容易被忽略，很多“默认声音从禁止的设备出来”的案例，最后都发现是它配错了。
- mixPort：混音端口，
role="source"表示这个端口向外输出混音后的音频数据，role="sink"表示接收输入数据。profile 定义了格式、采样率、声道掩码。 - devicePort：物理设备端口，
tagName是自己起的名字，type必须是框架定义的 AudioDeviceType，比如AUDIO_DEVICE_OUT_BLUETOOTH_A2DP。 - route：端口与端口之间的连接关系。
type="mix"表示这是一个混音连接，意味着混音端口的输出可以同时流向多个 sinks；如果是type="pass-through"则意味着固定点位直连，常见于 FM 等特殊场景。
2.3 常见修改场景：换默认输出、加 HDMI、限制路由
我在实际项目中总结出几个高频率修改点，写在这里供你参考。
第一个场景：产品需求是“开机后媒体声音默认走蓝牙音箱，蓝牙未连接时走扬声器”。这种情况只把defaultOutputDevice改成蓝牙是不够的，因为策略配置还需要保证蓝牙设备动态可用。正确做法是在primary模块下增加 A2DP 设备的 devicePort，并在 routes 里添加对应连接，同时把defaultOutputDevice配置为Speaker，由上层 AudioService 维护蓝牙连接后的动态切换。系统层的行为是“配置负责底线，运行时动态切换负责体验”。
第二个场景：新增 HDMI 音频输出。通常要在配置里新增一个模块（比如module name="hdmi"），添加对应的 devicePort 并挂到某个 mixPort 下。但要注意，HDMI 有时候不只是输出设备，还牵扯 HDCP、EDID 解析，这些并不是一个 XML 配置能解决的，需要 HAL 层配合。
第三个场景：限制某个设备作为输出。例如某些行业平板不想让媒体声音从听筒出来，除了在产品代码里限制之外，更稳妥的方案是不要在 routes 里把primary output连接到听筒设备。配置直接掐断，比代码里写一堆 if else 要可靠得多。
3. 音频策略配置实操：从修改到落地验证
3.1 修改前需要准备什么
动手改配置之前，确认以下条件：
- 有一台可以
adb root的设备或模拟器，方便直接替换配置并验证。 - 设备上
/system分区可写，或者具备重新编译 boot image 的环境。 - 准备好
adb pull和adb push工具链，以及支持 root 访问的文件管理器（用于验证权限）。 - 强烈建议给设备做一次完整备份，因为配置错误会导致音频服务反复 crash，严重时开机卡在启动阶段。
如果你只是做初步验证，不打算改系统镜像，在有 root 权限的设备上，可以直接替换/system/etc/audio_policy_configuration.xml后重启。但要注意，新版本 Android 对/system分区做了动态分区保护，直接 push 可能因只读挂载而失败，需要先adb remount，而且 remount 后会强制关闭 dm-verity，有一定风险。在正式项目中，我会把这些修改提交到源码，走完整的编译流程，而不是直接在设备上临时改文件。
3.2 完整流程一：提取当前配置
先看看设备上当前生效的配置长什么样：
adb root adb remount adb pull /system/etc/audio_policy_configuration.xml拿到文件后，先用文本编辑器打开，确认设备当前实际内容与源码中的差异。这一步很重要，因为很多厂商会在编译阶段用脚本对配置做后处理，直接改源码文件而不看实际烧录内容，很容易做出错误判断。
3.3 完整流程二：修改并验证路由行为
以“默认媒体音频输出从扬声器改为有线耳机优先”为例。思路是调整音频策略的优先级，让有线耳机在插入时自动成为媒体音频的输出目标。虽然 Android 默认策略已经对 wired headset 做了动态切换，但某些定制 ROM 会屏蔽掉耳机检测，导致耳机插入后系统无感知。
你需要做三件事：
第一，确认AudioPolicyManager是否能够识别耳机设备。在配置文件的devicePorts里，确保存在类型为AUDIO_DEVICE_OUT_WIRED_HEADSET的 devicePort：
<devicePort tagName="Wired Headset" type="AUDIO_DEVICE_OUT_WIRED_HEADSET" role="sink"> <profile name="" format="AUDIO_FORMAT_PCM_16_BIT" samplingRates="48000" channelMasks="AUDIO_CHANNEL_OUT_STEREO"/> </devicePort>第二，在 routes 里把该设备连接到主混音端口：
<route type="mix" sink="Wired Headset" sources="primary output"/>第三，确认attachedDevices里不要写死某个 device，否则可能导致动态设备切换失效。若产品要求耳机插上后就切过去，那么defaultOutputDevice可以保持为扬声器，由框架在耳机插入事件中动态切换路由。
改完配置后，重启设备，然后用命令验证路由决策：
adb shell dumpsys audio重点看输出里的Output devices和Routes段落。耳机插入前后对比，能够清晰看到当前 active output device 是否发生了切换。另外用 logcat 过滤 AudioPolicyManager 的日志，也能看到设备插入事件的处理流程。
3.4 配置校验与常见错误
我见过最多的配置错误，大概是这几类：
- name 重复：两个 devicePort 的 tagName 完全一样，导致策略匹配混乱。
- type 写错：例如把
AUDIO_DEVICE_OUT_SPEAKER写成AUDIO_DEVICE_OUT_SPEAKER_SAFE，设备无法识别。 - profile 参数不匹配：mixPort 支持的采样率与 devicePort 不一致，导致 AudioFlinger 做重采样，甚至无输出。
- route 指向不存在的端口：XML 解析阶段不会立刻报错，但运行时会静默失败，表现为声音莫名无声。
推荐一个检查方法：把修改后的配置文件放在源码树中执行mmm frameworks/av/services/audiopolicy/后编译，或在已有工程中使用 audio policy 的单元测试。对于快速验证，可以用xmllint先查一遍格式问题：
xmllint --noout audio_policy_configuration.xml3.5 关于 SELinux 的提醒
文件改对了只是第一步。在 Android 这个体系里，安全策略往往会给你上一课。/system/etc/audio_policy_configuration.xml被音频服务读取，正常情况下有系统权限。如果你是动态替换文件，可能需要关注 SELinux 上下文是否正确。尤其是在 vendor 分区和 system 分区的配置不同时，别忽略进程的 denial 日志：
adb shell dmesg | grep avc如果在 logcat 里看到 avc denied 且涉及 audioserver 或者 mediaserver，就需要补充或修正 SELinux policy，否则即使配置正确，服务也读不到，音频照样罢工。
4. 应用层的音频配置：不碰系统代码也能影响声音
很多人以为音频系统配置只对 Framework 和 HAL 开发有意义，其实应用开发者也会在不知不觉中和这套策略打交道。最典型的就是AudioAttributes和音频焦点。
4.1 AudioAttributes 是应用给系统的“说明书”
在 Android 5.0 之后，所有播放声音的 API 都建议携带AudioAttributes。它告诉系统两个重要信息：usage（用于什么场景）和contentType（内容是什么类型）。
- 播放音乐、游戏音效，应该设置
USAGE_MEDIA或USAGE_GAME。 - 导航语音，推荐
USAGE_ASSISTANCE_NAVIGATION_GUIDANCE。 - 闹钟提醒，使用
USAGE_ALARM。 - 通话相关，使用
USAGE_VOICE_COMMUNICATION或USAGE_VOICE_COMMUNICATION_SIGNALLING。
这些 usage 不只是一个标签，它会直接影响两个行为：音量分组和焦点策略。比如误把闹钟声音设置成USAGE_MEDIA，用户调“媒体音量”就能把闹钟调静音，这在产品上是很危险的。我曾经接诊过一个“闹钟不响”的工单，查到最后就是 App 用了错误的 usage，闹钟走了媒体音量流，被用户自己调静音了。
对于AudioTrack，创建时这么设置：
AudioAttributes attributes = new AudioAttributes.Builder() .setUsage(AudioAttributes.USAGE_MEDIA) .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) .build(); AudioTrack track = new AudioTrack.Builder() .setAudioAttributes(attributes) .setAudioFormat(format) .setBufferSizeInBytes(bufferSize) .setTransferMode(AudioTrack.MODE_STREAM) .build();4.2 音频焦点：系统配置之外的“动态路由”
音频焦点（Audio Focus）是和应用交互最频繁的机制。它的核心价值是防止多个应用同时出声，让系统能够根据“谁抢到了焦点”来调整音量或暂停播放。
在使用AudioFocusRequest时，很多开发者会忽略setFocusGain的语义：
AUDIOFOCUS_GAIN：长时间持有焦点，适合音乐播放。AUDIOFOCUS_GAIN_TRANSIENT：短时间内持有，适合铃声、提示音。AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK：允许其他应用降低音量继续播放，适合导航语音。
我见过不少“播放音乐时导航说话，音乐直接暂停而不是降低音量”的体验问题，根因就是导航 App 申请焦点时用了GAIN而不是MAY_DUCK。这个问题不需要改系统任何配置，纯粹是应用层参数选择问题，但最终表现出了“配置文件”一样的系统性影响。
另一个常见坑是焦点请求与释放必须成对。如果请求了AUDIOFOCUS_GAIN却在onAudioFocusChange回调里不处理LOSS，或者播放结束不abandonAudioFocusRequest，就会导致其他应用一直拿不到焦点，整个设备的媒体播放体验都会变得奇怪。
4.3 音频文件访问与 FileProvider：一条热搜词背后的实战场景
打开热搜词列表，你会看到大量形如content://com.tencent.wework.fileprovider/external_path/android/data/com...的路径。这其实揭示了一个和音频配置关系很深的场景：App 怎么读取来自其他应用的音频文件。
从 Android 7.0 起，file://URI 的跨应用共享被禁止。你不能再拿着一个/storage/emulated/0/...的路径去让别的应用读取，系统会直接抛FileUriExposedException。而从 Android 10 开始的分区存储，又进一步加强了对公共目录的限制。于是，各家应用开始提供FileProvider，对外暴露content://URI。
解析一下这条典型路径：
content://com.tencent.wework.fileprovider/external_path/android/data/com...com.tencent.wework.fileprovider是 provider 的 authority，通常在 AndroidManifest 里唯一声明。external_path是 FileProvider<paths>配置中定义的名称。- 后面的路径段是要共享的子目录。
如果你的 App 要播放另一个 App 分享过来的音频，一定要用ContentResolver打开 URI，而不是把字符串当成文件路径处理。例如：
val uri = Uri.parse("content://xxx.fileprovider/external_path/audio/test.mp3") contentResolver.openFileDescriptor(uri, "r")?.use { pfd -> // 交给 MediaPlayer 或 AudioTrack 使用 }对于自己声明 FileProvider，AndroidManifest 里大致是这样：
<provider android:name="androidx.core.content.FileProvider" android:authorities="${applicationId}.fileprovider" android:exported="false" android:grantUriPermissions="true"> <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/file_paths" /> </provider>file_paths.xml中按需声明external-path、external-files-path、files-path等根路径。这里有一个常踩的坑：<external-path>对应的是Environment.getExternalStorageDirectory()，而<external-files-path>对应的是getExternalFilesDir()。很多开发者把两者混用，导致明明文件存在，但解析 URI 时却报“无法打开文件”。
在实际开发中，如果你收到一个来自微信或企业微信分享的音频文件，并需要对它做转码、播放或者本地缓存，最好先通过OpenableColumns查询到真实的显示名和大小，然后拷贝到自己的应用目录下再操作。直接跨应用流式读取不是不行，但文件句柄的生命周期一旦没控制好，很容易出现句柄泄漏。
contentResolver.query(uri, null, null, null, null)?.use { cursor -> val nameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME) val sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE) cursor.moveToFirst() val fileName = cursor.getString(nameIndex) val fileSize = cursor.getLong(sizeIndex) }这部分看似和音频配置没直接关系，但我在调研“音频文件打不开”“无法播放分享的录音”这类问题时，十次有八次的根因都在 FileProvider 配置或 URI 处理上。它在音频链路里就是“入口关卡”。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 播放音乐完全无声 | 路由配置错误、音量曲线为零、焦点被抢占 | dumpsys audio查看 active output；检查音量分组 |
| 声音从错误设备输出 | routes 配置不当、默认输出设备设置错误 | 修改defaultOutputDevice与 routes，对比插入设备前后状态 |
| 耳机插拔无反应 | devicePort 缺失或 HAL 未上报 | 查看 logcat 中的AudioPolicyManager日志，确认 device connection 事件 |
| 蓝牙连接后还是没有声音 | A2DP 设备未列入 routes 或 module 名为a2dp配置不全 | 确认 A2DP module 的 profile 匹配，测试其他蓝牙耳机 |
| 闹钟静音后不响 | App 用了错误的AudioAttributes.usage | 将 usage 改为USAGE_ALARM |
| 播放导航语音导致音乐暂停 | 焦点申请使用了 GAIN 而非 MAY_DUCK | 调整focusGain为AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK |
| 其他应用分享的音频无法播放 | FileProvider 路径配置错误或 URI 被当文件路径处理 | 校验file_paths.xml；使用 ContentResolver 读取 |
| 修改配置后系统反复重启 | XML 语法错误、端口名不匹配 | xmllint校验；替换回原配置恢复 |
5.2 独家排查三步法
第一步：抓全局状态。出了问题先执行adb shell dumpsys audio，观察全局输出。重点看 audio policy 里的Output devices、Input devices、Routes和Audio Focus Stack。这一个命令能回答很多“现在实际在走哪条路”的问题。
第二步：过滤关键日志。AudioPolicyManager 和 AudioFlinger 的关键决策都会写入 logcat，只不过总开关默认不开。可以先用adb shell setprop log.tag.AudioPolicyManager VERBOSE打开详细日志，然后复现问题。音频路由变化、设备插拔、焦点请求都会被记录下来。
第三步：动态缩小范围。先卸载第三方音频应用，排除应用层干扰；再切到安全模式，排除自启动 App 的影响；最终定位到这个行为是不是纯系统复现。如果纯系统就能复现，那么就去查配置；如果不能，那就顺着应用进程的 binder 调用去查。
5.3 修改系统配置的避坑心得
直接替换配置文件这种操作，做完一定要检查文件权限。烧录进系统的配置文件，权限通常为0644，属主root:root。如果 push 后权限不对，音频服务可能直接读取失败。
另一个容易栽的事情是文本编辑器的换行符和 BOM。Windows 下编辑过的 XML 文件经常带 BOM，虽然很多解析器能容忍，但 XML Schema 校验会直接失败，稳妥的做法是保存为 UTF-8 无 BOM 格式，用 VS Code 或 Notepad++ 都能设置。
还有一条比较隐蔽的经验：同一台设备上可能存在多个 audio_policy_configuration.xml。不同模块、不同分区各自带一份。修改前务必确认服务实际读取的是哪一份，别改了个寂寞。判断方法简单，把其中一份内容故意改错，重启看服务崩溃日志里的文件路径，你就能知道实际引用的是哪一个了。
另外，遇到 “音质不好” 和 “声音延迟大” 的问题时，别急着改 policy 里的采样率。先确认 HAL 层设备能力，再用dumpsys media.audio_flinger里的线程信息查看当前重采样状态。配置里写着支持 48kHz，但 HAL 实际只暴露了 44.1kHz，音频服务就会默默做重采样，延迟和音质损失都来源于此。
5.4 关于 AudioPolicy 的进一步调试技巧
对于需要深入了解路由决策的场景，可以开启 audioserver 的 verbose 日志，或者直接抓取systrace来观察音频链路的调用耗时。在 Android 10 及以上设备上，还能通过adb shell cmd audio进行部分策略动态调整，这在快速测试路由策略时非常方便。
例如，查看当前有声策略：
adb shell cmd audio list-policies需要提醒的是，cmd audio在不同 Android 版本上的子命令差异较大，使用时先执行adb shell cmd audio help看看当前的版本支持哪些操作。它适合在线调试，但如果是需要固化到产品的路由规则，仍然建议走到源码和配置里。
写在最后
处理音频问题这么多年，我的体会是：这套体系虽然复杂，但核心思路很清晰——策略配置决定能力边界，运行时状态决定当下路由，应用属性决定用户体验。遇到诡异问题，第一反应不要是改应用代码，先从系统状态出发，搞清楚“系统认为你在干什么”，再决定动哪里。音频配置从表面上看是一堆 XML 标签，但实际牵扯到 HAL 实现、SELinux 策略、Framework 运行机制，任何一个环节不匹配，都会以“莫名其妙”的音频问题呈现在你面前。希望这篇拆解能帮你少踩几个坑，在排查音频问题时有一点“通关地图”的感觉。
