[Bug] 音量键翻页在 Android 14+ 闪退的真正根因：依赖库 react-native-volume-manager 的 registerReceiver 缺 Android 14 receiver flag（非 app/JS 层问题，附标准修法）

[chy5301]

Type

Bug（根因分析 / 现有功能因崩溃被下线）

关联

• 深化 [Bug] 移动端音量键翻页功能已实现但阅读设置面板缺少开关，用户无法启用 / Volume-key paging is implemented on mobile but has no toggle in reader settings #379（移动端音量键翻页缺设置开关）
• 为 fix(reader): 移动端阅读设置面板补「音量键翻页」开关 / Add missing volume-key paging toggle to mobile reader settings #380（补开关 PR）提供「合并前需先解决」的根因依据
• 背景：你在 移动端翻页建议 #28 提到「之前在部分安卓机有闪退就回退了」，对应 commit 66c0133「fix: hide volume button paging setting to avoid crash bug」

TL;DR

崩溃不是 app / JS 层的问题，而是依赖库 react-native-volume-manager@2.0.8 的一行原生代码在 Android 14 (API 34) 的破坏性变更下抛出未捕获的 SecurityException，导致原生层闪退。这是整个 RN 生态都普遍踩过的坑，有高度标准化的修法。但在把开关加回来之前，还有一个 iOS 取舍的产品决策需要拍板（详见末尾）。

说明：以下是基于真实安装的库原生源码 + Android 官方文档 + 多个同源 RN 库崩溃案例的静态分析结论，置信度高；尚缺一份线上崩溃堆栈实证（见「待确认」）。

真正的根因

崩溃发生在依赖库 react-native-volume-manager 的 Android 原生侧 VolumeManagerModule.java：

private void registerVolumeReceiver() {
  if (!volumeBR.isRegistered()) {
    IntentFilter filter = new IntentFilter("android.media.VOLUME_CHANGED_ACTION");
    mContext.registerReceiver(volumeBR, filter);   // ← 缺 RECEIVER_EXPORTED/NOT_EXPORTED，且无 try/catch
    volumeBR.setRegistered(true);
  }
}

• 从 Android 14 (API 34) 起，targetSdk ≥ 34 的 app 注册非系统保护广播的 context-registered receiver 必须显式传 RECEIVER_EXPORTED 或 RECEIVER_NOT_EXPORTED，否则 registerReceiver 抛 java.lang.SecurityException。VOLUME_CHANGED_ACTION 正属于此类。
• 本项目 targetSdkVersion = 35（Expo SDK 54 默认，app.config.js 的 expo-build-properties 未覆盖），故命中。
• 该调用在原生侧无 try/catch，异常逃逸到原生主线程 → 进程闪退。

触发链（三条路径都经过这行）：

开启开关 → useVolumeButtonPaging active
  → addVolumeListener → 原生 addListener("RNVMEventVolume") → registerVolumeReceiver() → 闪退
  （另外两条：每次翻页后 setVolume 收尾重注册广播、从后台切回前台 onHostResume 重注册广播，同样崩）

这完美解释了两个现象：

1. 「部分机型」= Android 14 / 15。Android 13 及以下不要求该 flag，完全不崩——所以是「部分」机型。
2. JS 层怎么都定位不到：崩溃是 Java 层未捕获异常，JS 的 try/catch / console.warn 物理上接触不到，Metro 日志里什么都看不到。功能逻辑、原生桥接、那个设置开关本身都没有问题。

受影响范围只增不减：该限制是 Android 的安全收紧，Android 15 (API 35) / 16 (API 36) 只会延续、不会放宽；本项目 targetSdk = 35 固定（Google Play 强制逐年跟进），所以决定崩不崩的只是「用户设备是不是 Android 14+」。随着用户设备升级，今天的「部分机型崩溃」会逐步扩大为「多数机型崩溃」——这也是建议尽早处理的理由。

这是 Android 14 的普遍问题，已有标准修法

这是 Android 官方文档化的破坏性变更（Behavior changes — Runtime-registered broadcasts receivers must specify export behavior）。整个 RN 生态都出现过同一个 SecurityException 并已修复，修法高度一致：

库	结局
react-native（core 自身）	已修，commit 177d97d 新增 compatRegisterReceiver
react-native-netinfo	已修并发版（NetInfoUtils.java，issue #681）
react-native-track-player / purchases / blob-util / callkeep / share	均同款已处理

标准修法（可直接照搬 RN core / netinfo）：

if (Build.VERSION.SDK_INT >= 34 && context.getApplicationInfo().targetSdkVersion >= 34) {
    context.registerReceiver(receiver, filter, Context.RECEIVER_NOT_EXPORTED);
} else {
    context.registerReceiver(receiver, filter);
}
// 或一行：ContextCompat.registerReceiver(ctx, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED)

对 VOLUME_CHANGED_ACTION 这类只进不出的系统广播，选 RECEIVER_NOT_EXPORTED 最安全。

⚠️ 关键：react-native-volume-manager 上游 main 分支至今未修这行（我直接拉了 main 源码确认：第 79 行仍是裸的 registerReceiver，无 flag）。该库仍在维护——GitHub 上 2026-06 初刚发 v2.1.1——但 npm 的 latest tag 仍停在 2.0.8（上游 #62 正在催「publish v2.1.0 to npm」），且 2.1.x 同样未修此行。仓库历史上有数个 Android 崩溃类 issue（#9「Crash on android: Receiver not registered」、#38「Android crash on foregrounding」、#32「setupKeyListener NPE」），但没有一条专门指向本案的 Android 14 RECEIVER_EXPORTED 问题。因此无法靠升级解决，需 app 侧自行处理：① patch-package 改库源码（本仓库已有 patches/ 机制）；或 ② 在原生 MainApplication 覆写 registerReceiver 兜底补 flag。

平台兼容性真相（这点可能和直觉相反）

在决定怎么修之前，有必要先澄清两端的真实情况——因为它会影响方案选择：

	iOS	Android
现状方案（监听系统音量变化→翻页→还原音量）	✅ 能用（库用 AVAudioSession.outputVolume KVO + 隐藏 MPVolumeView，崩溃风险低）	❌ Android 14+ 闪退（即本 issue）
业界主流方案（原生拦截 KEYCODE_VOLUME_* 并消费，不碰音量）	❌ iOS 拿不到音量键事件，根本无法实现	✅ 治本

也就是说：现状方案是「iOS 能用、Android 会崩」；而看起来更优雅的「拦截按键」方案恰恰 iOS 完全不支持（react-native-keyevent 的 iOS 端只支持外接键盘字母键；Moon+ Reader / KOReader 等成熟阅读器的音量键翻页也都是 Android-only）。

修复方案与一个需要拍板的产品决策

核心决策点：iOS 要不要支持音量键翻页？ 这决定走哪条路。

• 方案 ①｜最小补丁止血（保留现状架构）：给那行 registerReceiver 加 flag（如上）。改动最小、风险极低、两端都保留、可最快发版。代价：现状架构的固有副作用仍在（见下「次要问题」）。
• 方案 ②｜Android 改用按键拦截 + iOS 保留现状：Android 用 react-native-keyevent 在 onKeyDown 拦截音量键（治本，且因为不再注册广播，顺带绕开本崩溃），iOS 沿用音量监听。体验最佳，代价是维护两套实现。
• 方案 ③｜统一改用按键拦截：最干净、最治本，但 iOS 将不再支持音量键翻页（符合业界主流，但要接受放弃 iOS）。

我个人倾向于 ① 先止血、或 ② 兼顾两端，避免放弃 iOS——但这属于产品取舍，最终由你定夺。

顺带发现的次要问题（现状「监听音量」架构的固有缺陷，供参考）

即使只走方案 ①，以下几点也建议知悉：

1. 边界失效：现状靠「音量增减方向」判翻页方向，当系统媒体音量已在最大/最小时，按键不产生音量变化 → 翻页失灵（用户会以为开关坏了）。
2. 回环与信号不纯：「改音量 → 广播 → 判向翻页 → 再还原音量 → 又一次广播」存在回环；且 MUTE 键、蓝牙耳机调音量、媒体会话等外部音量变化都会混入被误判。
3. 与 TTS 抢占：现状改 STREAM_MUSIC，所以只能用 ttsPlayState === "stopped" 守卫，等于「TTS 播放时音量键翻页不可用」。
4. 库内另两处裸露点（非本崩溃主因，但同类风险）：setupKeyListener 的 adjustStreamVolume 无 try/catch；setVolume 的 catch 分支内 startActivity 缺 FLAG_ACTIVITY_NEW_TASK（仅当还原目标音量为 0 时触发）。
   • 注：现状对「勿扰模式改音量抛 SecurityException」其实是安全的——库的 setStreamVolume 已包了 try/catch，不会因此崩（只会还原失败），所以 DND 不是本崩溃的根因。

待确认

本结论以静态分析为主，尚无一份线上崩溃堆栈直接坐实。若方便，建议在一台 Android 14/15 真机或模拟器 上：开启音量键翻页 → 进入阅读页 → adb logcat 抓取，确认崩溃栈是否指向 VolumeManagerModule.registerVolumeReceiver 的 SecurityException。另：若当时有用户反馈过具体崩溃机型 / Android 版本，也可补充进来进一步佐证。