用 Trae 把 Android 6.0 到 9.0 的兼容性一次性理顺,同时把 targetSdk 拉到 36

4 阅读9分钟

去年接手一个 2019 年停更的项目时,我面对的是这样一套配置:minSdk 21,targetSdk 28,Gradle 插件停在 4.x,通知还在用裸 Notification.Builder,拍照还在 Uri.fromFile()。而 Google Play 对 targetSdk 的要求已经推进到了 36。把 targetSdk 从 28 直接拉到 36,中间要跨过 Android 10 到 16 的每一道行为变更;而下游还要保证在 6.0 到 9.0 这批老设备上不能崩。

这不是一个“升级一下版本号”的任务,而是一个双向兼容问题:上要满足最新 API 的强制要求,下要守住 6.0 到 9.0 的行为底线。Trae 在这类任务里的定位很明确——它负责识别、批量修改和生成 diff,但哪些改动可以自动化、哪些必须人工逐行核对、哪些必须真机验证,这条边界必须由你来划。

一、先看清 6.0 到 9.0 这条“断层带”上到底有什么

Android 6.0 到 9.0 之所以是老项目兼容性的重灾区,是因为这四年恰好是 Android 权限模型、文件访问模型和后台执行模型集中收紧的阶段。每一层变更都不是孤立的,它们会叠加:

6.0(API 23)运行时权限。 这是第一道分水岭。targetSdk ≥ 23 之后,危险权限必须在运行时请求,checkSelfPermission / requestPermissions 成为标配。老项目里大量 Manifest.permission 声明后直接调用的代码,在这个阈值上会直接抛 SecurityException。

7.0(API 24)FileProvider 强制。 把 file:// Uri 暴露给其他应用会触发 FileUriExposedException。拍照、裁剪、安装 APK 这些场景必须切换到 FileProvider 的 content://。这里有一个容易被忽略的细节:6.0 及以下并不强制要求 FileProvider,所以如果你的 minSdk 是 23,代码里就需要保留版本分支,而不是一刀切全改。

8.0(API 26)通知渠道 + 后台限制。 所有通知必须归属到一个 NotificationChannel,否则在 8.0+ 设备上直接不显示。与此同时,后台服务被大幅收紧,startService 在后台场景下会抛 IllegalStateException,需要迁移到 JobScheduler 或 JobIntentService。通知渠道还有一个隐蔽的坑:渠道一旦创建,重要性等级和声音等属性由用户控制,应用侧无法再改回,所以渠道 ID 和初始配置要在设计时一次定好。

9.0(API 28)明文流量默认关闭。 targetSdk ≥ 28 之后,isCleartextTrafficPermitted() 默认返回 false,所有 HTTP 请求会被系统拦截,除非你在 Network Security Config 中为特定域名显式放行。老项目里如果还有硬编码的 HTTP 接口,这一步会直接表现为网络请求大面积失败,而不是编译错误——更容易被漏测。

二、Trae 在这个场景里应该做什么,不应该做什么

理解了上面的断层带之后,Trae 的价值就清楚了:它是一个能读懂工程语义的批量修改器,但不是一个兼容性判断器。

兼容性问题的判断依据往往不在代码本身,而在设备的实际行为、厂商 ROM 的偏离程度、以及 targetSdk 阈值触发的具体分支逻辑。这些信息 Trae 拿不到。它能做的是:扫描全部 AndroidManifest.xml 和 build.gradle,列出所有仍在使用 file:// 的代码位置;识别所有 Notification.Builder 调用并批量补上渠道参数;把散落在各处的 Build.VERSION.SDK_INT 检查收敛到统一的位置。它不能做的是:替你决定某个 HTTP 域名到底该不该放行,替你判断某个渠道的重要性等级设成 HIGH 还是 DEFAULT,替你验证 FileProvider 的 authorities 在厂商 ROM 上是否冲突。

所以协作的起点不是“让 Trae 直接改”,而是先让它产出一份兼容性现状清单。

三、用 Skill 而不是 Rules 来承载兼容性约束

Trae 的 Rules 是全量加载的,一旦开启对话,所有规则都会占用上下文窗口。对于兼容性适配这种涉及大量文件、需要反复分批处理的任务,把几十条版本约束塞进 Rules 会让 Agent 在日常对话里持续分心。

更合适的是 Skill。Skill 是按需加载的:Agent 先扫描技能的简要描述,判断当前任务相关后才加载完整内容。你可以把 6.0 到 9.0 每一层的适配规则写得很细,而不用担心它干扰你日常写业务逻辑的对话。

一个兼容性 Skill 的骨架可以长这样,放在 .trae/skills/android-compat-6to9/SKILL.md:

markdown

---
name: android-compat-6to9
description: 处理 Android 6.0-9.0 兼容性适配时使用。涉及运行时权限、FileProvider、通知渠道、明文流量、版本分支判断时触发。
---

## 版本基线
- minSdk = 23,targetSdk = 36
- 禁止删除任何 `Build.VERSION.SDK_INT` 分支而不给出替代方案
- 涉及 API 24+ 的改动,必须同步检查 API 23 的降级路径

## 运行时权限(6.0+)
- 所有 dangerous permission 的调用点,必须确认存在 checkSelfPermission + requestPermissions 完整链路
- 不要用 `@SuppressLint("NewApi")` 绕过,新增权限请求时注明对应的 API 级别

## FileProvider(7.0+)
- 任何向其他应用传递文件的 Intent,必须使用 FileProvider.getUriForFile
- 同时保留 API 23 的 file:// 路径作为降级,除非 minSdk 已明确提升到 24
- FileProvider authorities 使用 `${applicationId}.fileprovider` 格式,避免厂商 ROM 冲突

## 通知(8.0+)
- 所有 Notification 构建路径必须有对应的 NotificationChannel 创建逻辑
- 保留 NotificationCompat 的 setPriority 调用,用于 7.1 及以下降级
- 渠道 ID 一旦出现在代码中,标记为不可更改

## 明文流量(9.0+)
- 不自动将 http:// 替换为 https://,只标记并输出清单
- 需要放行的域名必须通过 Network Security Config 配置,禁止建议 usesCleartextTraffic="true"

四、targetSdk 从 28 拉到 36:AI 能帮你改什么,你必须自己盯什么

Google Play 的要求是明确的:从 2026 年 8 月 31 日起,新应用和应用更新必须 targetSdk ≥ 36(Android 16)。如果你的老项目还停在 28,这一步绕不过去。

从 28 到 36 的行为变更跨度很大,但 Trae 在这里能发挥的作用是有明确边界的。

它可以高效完成的:

批量扫描所有 PendingIntent 调用,补上 FLAG_IMMUTABLE 或 FLAG_MUTABLE(Android 12 起的强制要求);识别所有 POST_NOTIFICATIONS 缺失的运行时请求路径(Android 13 起通知权限变成运行时权限);把 AndroidManifest.xml 中缺失 android:exported 的组件批量列出,供你逐条判断该设 true 还是 false(Android 12 起带 intent-filter 的组件必须显式声明)。

它不应该独立完成的:

Android 16(API 36)对边到边模式的强制要求。以 36 为目标平台的应用,windowOptOutEdgeToEdgeEnforcement 属性被废弃并停用,应用无法选择退出边到边模式。这意味着状态栏和导航栏区域的布局需要重新核对,而 Trae 无法判断你的 ConstraintLayout 在全面屏手势导航下是否会被遮挡。这类改动必须回到 Android Studio 的 Layout Inspector 和真机上逐屏确认。

同样,minSdk 保持 23 意味着你仍然需要为 6.0 的设备维护降级路径,而 targetSdk 36 的行为变更是在“设备运行 Android 16 且应用以 36 为目标”时才生效的。这两套逻辑在同一份代码里并存,AI 很容易在修改高版本路径时误删低版本的 fallback。这就是为什么 Skill 里要明确写死“禁止删除任何 Build.VERSION.SDK_INT 分支而不给出替代方案”。

五、一个容易忽略的细节:minSdk 23 时,multidex 和 Jetifier 都是历史包袱

如果你的老项目还开着 multiDexEnabled true 并依赖 Multidex 支持库,在 minSdk ≥ 21 的前提下,这些配置已经不再必要了。同样,android.enableJetifier=true 是为 support 库到 AndroidX 的过渡服务的;如果依赖树里已经没有 support 库坐标,Jetifier 只会拖慢构建并引入潜在的符号冲突。

这两项清理用 Trae 来做是安全的:让它扫描 gradle.properties 和所有 build.gradle,确认 minSdk 值和剩余 com.android.support 依赖后给出移除 diff。但要守住一条:移除 Jetifier 之前,必须确认所有 AAR 依赖都已经迁移到 AndroidX,否则会在运行时抛出 ClassNotFoundException,而这个问题在编译期不一定暴露。

六、验证纪律:Trae 的“改完了”不等于“兼容了”

兼容性适配最危险的地方在于,很多问题的表现形式是运行时异常或功能静默失效,而不是编译错误。FileProvider 配置错了,编译能过,拍照时崩;通知渠道 ID 拼错了,编译能过,通知不显示;明文流量没放行,编译能过,请求全超时。

所以最终验证必须回到 Android 工具链,按版本分层:

编译层:./gradlew assembleDebug 通过只是起点,不是终点。

Lint 层:跑 ./gradlew lint,重点看 NewApi、InlinedApi 和 UnusedAttribute 三类问题。Lint 能发现很多 Trae 在代码语义层面看不到的 API 级别不匹配。

真机/模拟器层:至少覆盖 6.0(API 23)、7.0(API 24)、8.0(API 26)、9.0(API 28)和最新 API 36 五个节点。重点关注:权限拒绝后的降级行为、拍照/裁剪的 Uri 传递、通知在各版本上的显示、HTTP 接口在 9.0+ 上的可达性。

厂商 ROM 层:如果面向国内市场,小米、华为、OPPO 的后台限制和通知行为可能在标准 Android 行为之外另有偏离。Trae 无法替你测这些,只能在代码层面把厂商推送 SDK 和电池优化引导逻辑整理清楚。

写在最后

用 Trae 处理 Android 6.0 到 9.0 兼容性并拉到 targetSdk 36,真正高效的工作流不是“一句话让 AI 全改完”,而是:让 Trae 把分散在各处的版本分支、过时调用和缺失声明全部摊开,你来做“哪些能自动改、哪些必须人工核”的逐条判断,最后把验证交还给 Android 工具链和真机。

Trae 能在一分钟内告诉你项目里有多少处 Uri.fromFile、多少个 Notification 构建路径没有渠道参数、多少个组件缺 exported。但它不能替你决定 FileProvider 的降级逻辑该怎么写,不能替你判断边到边模式下你的布局会不会被手势条盖住,更不能替你在 6.0 的低配真机上跑一遍完整流程。

兼容性这件事,判断权始终在人的手里。Trae 把信息整理好、把重复劳动扛下来,已经足够了。边界守住了,它是拉高版本号这件事上最省力的工具;边界丢了,它会以同样的速度把兼容性问题埋进更深的地方。