编译通过只代表代码能编，不代表升级完成。
项目原来跑在旧 API 版本上，一切正常。开发者把 SDK 升级到 API 26，代码基本没改，编译也通过了。跑起来一测，三个地方出问题：权限申请行为变了、一个旧 API 被替换了、三方 HAR 还依赖旧接口。
这就是版本升级最容易踩的坑：以为改个版本号就行，实际上系统行为、接口定义、三方依赖全都变了。
一、compile SDK、targetSDK、compatibleSDK 分别是什么
这三个参数经常被搞混，先理清楚：
| 参数 | 作用 |
|---|---|
| compileSdkVersion | 编译时用哪个版本的 API |
| targetSdkVersion | 告诉系统：我适配到哪个版本 |
| compatibleSdkVersion | 最低支持到哪个版本 |
简单说：compileSdk 决定你能用什么新接口，targetSdk 决定系统要不要按新行为对待你，compatibleSdk 决定你最低能跑在哪个版本上。
很多人升级的时候只改了 compileSdkVersion，targetSdkVersion 没动。这样系统还是按旧版本的行为对待你的应用，看似没问题，但其实根本没测新行为。
二、API 新增、废弃、行为变更有什么区别
| 类型 | 说明 | 影响 |
|---|---|---|
| 新增 | 加了新接口 | 不影响旧代码 |
| 废弃 | 旧接口标记为 deprecated | 还能用，但以后会删 |
| 行为变更 | 接口名没变，行为变了 | 最容易出问题 |
最坑的是第三种：接口名没变，参数没变，但系统行为变了。这种你编译完全没问题，跑起来就不对。
三、API Change Assistant 怎么用
DevEco Studio 里有个 API Change Assistant 工具，专门用来分析升级影响。
它会扫描你的代码，列出：哪些接口被废弃了、哪些接口行为变了、哪些接口新增了需要适配。
这段代码解决什么问题： 检查升级后的 API 兼容性问题。
文件： 项目根目录
用途： API 升级影响分析
接入位置： 升级后第一步
1. 打开 DevEco Studio
2. 菜单栏 → Tools → API Change Assistant
3. 选择目标版本 API 26
4. 扫描项目代码
5. 查看报告这个工具能帮你快速定位问题，但不能代替人工测试。因为有些行为变更是运行时才会触发的，静态扫描看不出来。
四、第一个问题：权限行为变了
升级到 API 26 之后，原来申请存储权限的流程变了。旧版本是申请一次全量权限，新版本变成了细粒度授权。
代码没改，编译也通过，但跑起来发现权限申请弹窗都不弹了------因为旧的权限常量已经废弃了，要用新的权限枚举。
这个就是典型的"接口名没变，行为变了"的问题。编译完全正常，但运行时权限申请直接失败。
五、第二个问题：旧 API 被替换
第二个问题是有个文件操作的接口被替换了。旧的 fs.openSync 用法还能编译，但新版本里推荐用新的文件操作 API。
这个还好，至少编译的时候会有 deprecated 警告。照着警告改就行，不算太难。
六、第三个问题：三方 HAR 依赖旧接口
最麻烦的是第三个问题：项目依赖的一个三方 HAR 还在用旧版本的接口。
这个 HAR 不是我们写的，它编译的时候用的是旧 API。升级到 API 26 之后，这个 HAR 在新系统上跑起来就出问题了。
解决办法只有两个：要么等三方更新，要么把这个 HAR 的代码抽出来自己改。
这也是为什么升级的时候一定要检查三方依赖------你自己的代码没问题，不代表依赖的库没问题。
七、为什么升级完一定要重新做回归
很多人升级完只测一下主要功能，觉得能跑就行。但问题是：行为变更这种东西，往往出现在边缘场景里。
| 测试维度 | 检查点 |
|---|---|
| 新设备 | 新系统版本上所有功能正常 |
| 旧设备 | 旧系统版本上还能正常跑 |
| 权限相关 | 所有权限申请流程都测一遍 |
| 文件操作 | 所有文件读写路径都测一遍 |
| 三方依赖 | 所有引用的 HAR/HSP 都测一遍 |
不能只测最新设备，也不能只测主要功能。要把所有可能受影响的场景都过一遍。
这次升级完最大的体会是：版本升级不是改个版本号的事。compileSdk 改了，targetSdk 改了，不代表你真的适配完了。要跑一遍 API Change Assistant，要测权限、测文件、测三方依赖、测新设备旧设备。少测一个，上线之后就是一个线上 Bug。