Android 17 适配指南：API 37 行为变更与实战
Android 17（API level 37 / SDK 37）于 2026 年正式到来，又到了每年"适配新版"的季节。这一版的主旋律是隐私大收紧——本地网络访问、OTP 短信、联系人、无障碍服务全线加锁；同时持续推进 16KB 页面大小、前台服务规范化，并对 targetSdk 37 的 App 加了反射与自适应布局新要求。本文把所有 App 必改的"所有应用变更"和"targetSdk 37 专有变更"梳理成一份适配清单，配上代码与排查步骤，照着走就行。
官方行为变更（最权威）：所有应用的行为变更；targetSdk 37 专属变更。
1、Android 17 概述：两类变更要先分清
Android 17 的适配，第一步是分清两套变更的作用范围，别搞混排查优先级：
// 第一套：所有应用的行为变更（behavior-changes-all）
// 只要 App 跑在 Android 17 设备上就生效，不管你 targetSdk 是多少
// → 重点：本地网络权限、隐私四件套、16KB、无障碍收紧
// → 不适配 = 在 Android 17 设备上直接功能异常或崩溃
// 第二套：targetSdk 37 专属变更（behavior-changes-17）
// 只有 targetSdkVersion 设为 37 才触发
// → 重点：反射限制、自适应布局、局域网通信路径
// → Google Play 会逐步强制 targetSdk 37，早晚要面对
- 实操建议：先把"所有应用变更"查完（这些最紧急），再处理 targetSdk 37 升级
- 升 targetSdk 前务必在 Android 17 模拟器/真机全量回归，行为变更很多是"静默失败"
2、本地网络访问权限：影响面最大的新规
Android 17 新增了本地网络访问权限（Local Network Access Permission）：App 要发现或与局域网（LAN）设备通信，必须显式请求权限，系统通过"隐私保护 API"中介通信。这是继"存储权限"之后，又一个影响大量 App 的大权限变更。
// 谁受影响？（只要碰局域网就要适配）
// - IoT/智能家居控制（局域网发现设备）
// - 投屏 / 局域网文件共享 / 打印机
// - 局域网多人游戏、AirPlay/DLNA 类
// - 某些调试工具（adb over WiFi、抓包代理）
// 适配要点：
// 1. 按官方文档声明对应权限 / 使用系统提供的隐私中介 API
// 2. targetSdk 37 的 App 有"两条路径"：走系统中介 API，或声明本地网络权限
// 3. 用户首次触发局域网操作时，系统会弹权限请求，做好引导话术
排查方法：全局搜索项目中所有"局域网/IP 发现/mDNS/SSDP/组播"相关代码，逐一确认在 Android 17 上是否需要新权限。这块最容易被忽略——很多 App 平时没感知，但"连同一 WiFi 找设备"的功能在 Android 17 上会静默失败。
3、隐私四件套：OTP、联系人、无障碍、短信
Android 17 对几类敏感数据大幅收紧范围，合称"隐私四件套"：
// ① OTP / 验证码短信访问限制
// 只有"被授权的验证码处理者"才能读取 OTP 短信
// → 影响：自动填充验证码、短信类 App
// → 适配：改用官方 SMS Retriever / SMS User Consent API，别直接读短信库
// ② 联系人范围限制 + 新增 Contact Picker（联系人选择器）
// 不再轻易给"全量通讯录"读取权限
// → 影响：社交/通讯录备份/邀请类 App
// → 适配：用系统 Contact Picker 让用户"挑联系人"，替代 READ_CONTACTS 全量读
// ③ 无障碍服务访问收紧
// 只有"屏幕阅读器 / 明确授权的辅助应用"才能用无障碍服务
// → 影响：按键映射、自动化助手、悬浮窗类工具
// → 适配：这类 App 受冲击最大，需重新评估是否仍符合"授权辅助应用"资格
// ④ 短信 / 通话日志权限继续收紧
// 默认应用机制更严格，Play 上架审核更严
这四条的共同点是"从"声明权限就能读"变成"必须是合法用途 + 走系统 API"。如果你的 App 涉及验证码、通讯录、无障碍、短信任一项，务必逐一对照官方文档迁移到系统推荐 API，否则功能直接失效或被 Play 下架。
4、16KB 页面大小：含 native 代码的 App 必改
Android 17 继续推进16KB 页面大小（16 KB page size）为默认（Android 15 引入、16 强化、17 普及）。这对含 NDK / .so 库的 App是硬性要求：所有 native 库必须 16KB 对齐，否则在 16KB 设备上加载失败、直接崩溃。
// 检查你的 .so 是否 16KB 对齐
// 用 Android NDK 的工具检查：
// zipalign -c -P 16 -v 4 app-release.apk
// 或在 AGP 8.x+ 构建时自动检测
// 适配步骤：
// 1. 升级 Android Gradle Plugin（AGP）到 8.x+，构建时自动 16KB 对齐
// 2. 升级 NDK 到支持 16KB 的版本（r27+）
// 3. 重新编译所有 native 库（自家 + 第三方 SDK）
// 4. 排查代码里"写死 4096 的 mmap/页面假设"，改用 sysconf(_SC_PAGE_SIZE)
// 5. 在 16KB 设备/模拟器上跑通
// 经验：第三方闭源 so 是老大难 —— 联系厂商要 16KB 版本，或评估替换
最大的坑是第三方闭源 SDK：它们的 .so 可能没 16KB 版本，你无法自己重编译。务必尽早向 SDK 厂商要支持 16KB 的新版本，否则 Android 17 设备上你的 App 装不上。纯 Java/Kotlin 的 App（无 native）基本不受此条影响，但仍建议确认依赖的 SDK 是否含 native 代码。
5、前台服务（FGS）：声明与执行更严格
Android 17 对前台服务（Foreground Service）的"类型声明、启动时机、运行时执行"继续收紧，用得不规范的 App 会直接报错或被系统杀掉：
// 前台服务的"正确姿势"（Android 17 强化要求）
// 1. 必须声明 FGS 类型（dataSync / mediaPlayback / location / ...）
<service
android:name=".MyService"
android:foregroundServiceType="dataSync" />
// 2. 启动时指定类型（API 34+）
ContextCompat.startForegroundService(
context, Intent(context, MyService::class.java),
ForegroundInfo(type, notification)
)
// 3. 运行中"类型与实际行为"必须匹配，系统会校验
// 用 dataSync 类型但实际在做 mediaPlayback → 被判违规
// Android 17 的变化点：
// - 类型与权限的绑定更严（如 location 类型需前台位置权限）
// - 启动限制更严（从后台启动 FGS 的窗口继续收窄）
// - 长时间无操作的前台服务更易被回收
一句话："声明什么类型、就只做什么事、并持有什么权限"。如果你的 App 有一堆"万能前台服务"（一个 service 干多种活），Android 17 适配时要按职责拆分、各自声明正确类型。
6、targetSdk 37 专属：反射限制与自适应布局
把 targetSdk 升到 37 后，还会触发一组"专属变更"，最值得注意的是这两条：
// ① 反射修改 static final 字段 → IllegalAccessException
// targetSdk 37 起，通过反射修改"static final"字段会直接抛异常
// → 影响：各种"反射 hack"（改系统常量、改第三方库 final 字段、某些 ORM/序列化框架）
// → 适配：停止这类 hack；如果是框架内部行为，升级框架版本
// ② 自适应布局强制要求
// targetSdk 37 的 App 必须适配"所有设备形态"（平板、折叠屏、多窗口）
// → 不再允许"手机版硬撑到平板"的拉伸式布局
// → 适配：用响应式布局（ConstraintLayout/响应式资源/w600dp 断点）
// 确保在平板/多窗口下不崩、不丑
// ③ 局域网通信：SDK 37 有两条路径
// 走"系统中介 API" 或 申请"本地网络权限"，二选一
这两条背后是 Android 的两个长期方向：反射收紧（ART 与模块化要求"别 hack 系统内部"）和大屏适配（折叠屏/平板成主流，App 必须为多形态做好准备）。如果你有"反射改 final"的黑科技、或 App 在平板上还是"手机版硬放大"，这次都得改。
7、适配清单与排查流程
// ===== Android 17 适配 Checklist =====
// 1. 环境升级
// [ ] AGP 升到支持 37 的版本，compileSdk = 37
// [ ] NDK 升到 16KB 支持版本（r27+）
// [ ] targetSdk 评估是否升到 37（Google Play 会逐步强制）
// 2. 所有应用变更（最紧急，不管 targetSdk）
// [ ] 本地网络访问：所有局域网通信加权限 / 走中介 API
// [ ] OTP 短信：迁移到 SMS Retriever / User Consent API
// [ ] 联系人：改用 Contact Picker，少用 READ_CONTACTS 全量
// [ ] 无障碍：评估 App 是否仍符合"授权辅助应用"资格
// [ ] 16KB 页面大小：检查所有 .so 是否对齐，更新第三方 SDK
// [ ] 前台服务：类型声明、权限匹配、启动时机合规
// 3. targetSdk 37 专属（升 targetSdk 时做）
// [ ] 排查反射修改 static final 的代码，逐处移除/升级框架
// [ ] 自适应布局：平板/折叠屏/多窗口下回归测试
// [ ] 局域网通信路径选型（中介 API vs 权限）
// 4. 测试
// [ ] Android 17 模拟器 + 16KB 设备全量回归
// [ ] 重点回归：局域网、验证码、通讯录、前台服务、native 加载
8、最佳实践与避坑
- 早适配：16KB / 本地网络 / 反射这几条，越晚改越被动，第三方 SDK 是最大瓶颈
- 善用官方工具：`zipalign -P 16`、ADB 的行为变更检测、Android Studio 的 Lint
- 灰度发布：在 Android 17 设备上小流量验证，重点看"静默失败"的功能（局域网、OTP）
- 砍掉"反射 hack"与"万能前台服务"：这两类"历史欠债"在新版会集中暴雷
- 持续关注官方"behavior-changes-all"与"behavior-changes-17"页，Beta 期间可能有补充变更
- 第三方 SDK 专项排查：联系厂商确认是否已支持 Android 17 / 16KB，没支持的尽早替换
9、总结
Android 17（API 37）的适配，核心是"隐私大收紧 + native 对齐 + 规范化"。所有应用必改：本地网络访问权限、OTP/联系人/无障碍/短信的范围限制、16KB 页面大小、前台服务执行。targetSdk 37 专属：反射改 static final 抛异常、自适应布局强制、局域网通信路径。
关键要点：
- 两套变更：所有应用变更（最紧急）+ targetSdk 37 专属（升 targetSdk 时做）
- 本地网络权限是影响面最大的新规：所有局域网通信都要适配
- 隐私四件套：OTP 走官方 API、联系人用 Contact Picker、无障碍收紧、短信更严
- 16KB：含 native 的 App 必改，第三方闭源 so 是最大瓶颈
- targetSdk 37：砍反射 hack、做自适应布局，砍"万能前台服务"
对于 Android 开发者而言，每年的版本适配就像"体检 + 还债"——Android 17 这一年尤其如此：隐私合规的债（OTP/联系人/无障碍）、native 对齐的债（16KB）、反射与前台服务的债，都会集中到这次结算。建议趁 Beta 期就动手，先把"所有应用变更"排查一遍，再规划 targetSdk 37 升级，留足时间啃第三方 SDK 的 16KB 支持。把这次适配做好，你的 App 不仅能在 Android 17 上稳跑，整体架构也会更规范、更面向未来。
参考资料：
Android 17：所有应用的行为变更（官方）
Android 17：targetSdk 37 专属变更（官方）
What's new in Android security & privacy 2026（Google Blog）
Google Play target API level 要求（官方）
