Android17适配总结

Android 17 适配总结

版本： Android 17（API 37）

正式发布： 2026-06-16（Pixel）

官方文档： Android 17 · target 行为变更 · 全量行为变更

1. 适配目标

项	说明
`compileSdk` / `targetSdk`	37
Play 要求	预计 2027 年中起要求 target API 37（日期以官方为准）
适配分层	① 跑在 Android 17 上兼容（不升 target）→ ② 升 `targetSdk=37` 完整适配

kotlin 复制代码

android {
    compileSdk = 37
    defaultConfig {
        targetSdk = 37
    }
}

2. 高优先级必改项（升 targetSdk=37）

2.1 大屏方向 / 可调整大小 / 宽高比限制永久失效

sw >= 600dp 大屏上，系统忽略：
- screenOrientation / setRequestedOrientation()
- resizeableActivity=false
- minAspectRatio / maxAspectRatio
Android 16（API 36）的 opt-out 在 API 37 已取消
游戏类（Play 分类为 Games）仍可豁免

适配建议： 响应式布局、WindowSizeClass、Compose Adaptive / 多窗格；支持任意窗口尺寸与自由窗口。

2.2 局域网访问需权限

默认禁止访问局域网
需声明并运行时申请：ACCESS_LOCAL_NETWORK（属 NEARBY_DEVICES 权限组）
或改用系统隐私保护式设备选择器（可跳过弹窗）

影响： 投屏、智能家居、局域网发现/通信。

2.3 证书透明度（CT）默认开启

target 37 起，TLS 默认启用 Certificate Transparency
内网 / 企业自签 CA 若未上 CT 日志会失败

适配： 用 Network Security Config 按域名全局或局部 opt-out。

2.4 原生动态加载加固（Safer Native DCL）

Android 14 的 Safer DCL 从 DEX/JAR 扩展到 native .so
System.load() 加载的文件必须为只读，否则 UnsatisfiedLinkError

2.5 后台音频限制加强

后台播放 / 音频焦点 / 调音量等更严格
target 37：后台音频交互通常需 Foreground Service ，且满足其一：
- FGS 具备 while-in-use（WIU）能力
- 拥有精确闹钟权限，且使用 USAGE_ALARM 音频流

2.6 SMS OTP 保护扩大

标准短信中的 OTP（非 WebOTP / SMS Retriever 格式）：多数 target 37 应用 延迟约 3 小时才可读
期间 SMS_RECEIVED_ACTION 被拦截，SMS Provider 查询被过滤
默认短信应用、助手、配套应用等有豁免

适配： 迁移到 SMS Retriever 或 SMS User Consent API。

2.7 后台启动 Activity（BAL）收紧

保护扩展到 IntentSender
弃用 MODE_BACKGROUND_ACTIVITY_START_ALLOWED
改用更细粒度：如 MODE_BACKGROUND_ACTIVITY_START_ALLOW_IF_VISIBLE

2.8 MessageQueue 无锁实现

target 37 默认使用无锁 MessageQueue（DeliQueue）
反射访问私有字段/方法会失效 （如 mMessages 恒为 null）

适配：

去掉对 MessageQueue 内部结构的反射
测试库升级：Espresso 3.7.0+ 、Robolectric 4.17+
调试开关：adb am compat enable/disable USE_NEW_MESSAGEQUEUE <pkg>

2.9 `static final` 字段不可再改

反射修改 → IllegalAccessException
JNI（如 SetStaticLongField）→ 进程崩溃

影响： 依赖反射/JNI 改常量的热修、Hook、部分测试框架。

2.10 其他 target 37 变更（按业务排查）

变更	要点
ECH（Encrypted Client Hello）	TLS 可加密 SNI；可用 Network Security Config 配置
物理键盘密码显示	默认不再显示末位字符（`show_passwords_physical`）
蓝牙 RFCOMM `read()`	socket 关闭/断开时返回 `-1`，勿只靠 `IOException` 退出循环
通讯录 CP2	部分 PII 列从 Data view 移除；无 `READ_CONTACTS` 时严格 SQL 校验
自定义通知 View	进一步限制体积（堵住 URI 绕过）
NPU 访问	需声明 `FEATURE_NEURAL_PROCESSING_UNIT`（含 LiteRT NPU / 厂商 SDK / NNAPI）

3. 所有应用在 Android 17 上生效（与 target 无关）

变更	说明
跨 Profile 回环流量默认阻断	不能用 `127.0.0.1` 跨工作/个人 Profile 通信，无 opt-out
`usesCleartextTraffic` 计划废弃	明文 HTTP 请迁到 Network Security Config
应用内存限额	按设备 RAM 强制限制，超限可能被杀；`ApplicationExitInfo` 描述含 `MemoryLimiter:AnonSwap`
Activity 配置变更默认少重建	键盘/导航/触屏/色模式等默认走 `onConfigurationChanged()`；若必须重建需声明 `android:recreateOnConfigChanges`

4. 推荐适配清单（Checklist）

构建与基础

compileSdk / targetSdk → 37
Android Studio 更新到支持 API 37 的版本（推荐最新 Canary / 稳定版）
CameraX 升至 1.5.2 或 1.6.0+（避免 Android 17 动态范围相关崩溃）
第三方 SDK / 游戏引擎确认已声明支持 API 37

UI / 大屏 / 多窗口

去掉对方向锁定、不可调整大小的依赖（大屏）
验证折叠屏、平板、桌面模式、自由窗口、App Bubbles、交互式 PiP
配置变更路径：确认是否依赖 Activity 重建

网络 / 安全

HTTPS + CT；内网证书配置豁免
明文流量改 Network Security Config
局域网能力申请 ACCESS_LOCAL_NETWORK 或改用系统 Picker
动态加载的 .so 保证只读
排查反射/JNI 修改 static final

隐私 / 权限

OTP 改为 SMS Retriever / User Consent
联系人优先系统 Contact Picker，少用宽权限
后台音频：补 FGS / 权限策略
BAL：替换旧 MODE_BACKGROUND_ACTIVITY_START_ALLOWED

稳定性

去掉 MessageQueue 反射；升级 Espresso / Robolectric
蓝牙 RFCOMM 读循环处理 -1
内存：R8 Full Mode、泄漏排查、关注 Play Console 内存指标
使用 NPU 时声明 FEATURE_NEURAL_PROCESSING_UNIT

5. 测试建议

兼容测试（不升 target）：安装现网包到 Android 17 真机/模拟器，跑全流程
目标行为测试（升 target） ：targetSdk=37 后重点回归上表高优先级项
兼容性开关 ：开发者选项 / adb am compat 可单项开关 target 行为
大屏矩阵：手机 + 折叠 + 平板 + 桌面模式 / 外接屏
网络矩阵：公网 HTTPS、企业证书、局域网设备、明文 HTTP（若仍有）

6. 优缺点（升级 target 37）

	说明
优点	满足未来 Play 要求；大屏/多窗体验合规；隐私安全默认更强；MessageQueue/GC/内存策略带来性能与稳定性收益
缺点	大屏适配与响应式改造成本高；局域网/OTP/后台音频/CT 等行为易踩坑；反射与热修空间被进一步压缩；第三方 SDK 若未跟进会阻塞发版