将 NativeScript 项目升级到 Android API 35 级别

谷歌要求在2025年八月底之前将应用升级到目标 API 35 级别。这是意料之中的，因为 Android 15 计划在今年年底发布。

官方参考 ：
- Android 15 开发者预览版：https://developer.android.com/about/versions/15
- 谷歌 Play 商店 API 政策目标日期：https://support.google.com/googleplay/android-developer/answer/11926878

将你的 NativeScript 项目升级到目标 Android API 35（Android 15）对于保持与最新 Android 设备的兼容性以及遵守 Google Play 商店的要求至关重要。本指南将为你提供逐步说明，以确保升级过程顺利进行。

准备工作

在开始之前，请确保你已具备以下条件：

一个正在运行的 NativeScript 项目
系统上已安装 Node.js
已设置 Android 开发环境
可以访问项目的命令行

步骤一：更新 NativeScript 依赖项

将你的 NativeScript 项目升级到 Android 15 的基础是更新核心的 NativeScript 包。这些包包含了连接你的 JavaScript 代码和 Android 平台的关键桥梁。

在你项目的根目录下打开终端并运行：

bash 复制代码

npm update @nativescript/android @nativescript/core

然而，为了兼容 Android 15，你需要确保使用的是 8.9 或更高版本。检查你当前的版本：

bash 复制代码

npm list @nativescript/android @nativescript/core

如果你的版本低于 8.9，请明确安装最新版本：

bash 复制代码

npm install @nativescript/android@latest @nativescript/core@latest

为什么这很重要：这些包包含了你的应用所使用的 Android 特定运行时和 API。8.9 版本及以上包含了对 Android 15 新功能和安全要求的支持。

步骤二：升级 NativeScript CLI

NativeScript CLI 是你用于构建、运行和管理项目的命令行工具包。过时的 CLI 可能会导致与新版 Android 的兼容性问题。

更新你的全局 NativeScript CLI：

bash 复制代码

npm install -g @nativescript/cli@latest

验证更新结果：

bash 复制代码

ns --version

你应该看到 8.9 或更高的版本，以获得对 Android 15 的最佳支持。

步骤三：配置 Android SDK 版本

现在到了关键部分------告诉你的项目以 Android 15 为目标。这发生在你应用的 Gradle 配置文件中，这个文件就像是告诉 Android 构建系统如何编译你的应用的蓝图。

前往你项目中的 app/App_Resources/Android/app.gradle 文件，找到 android 部分。更新 compileSdkVersion 和 targetSdkVersion：

gradle 复制代码

android {
    compileSdkVersion 35
    buildToolsVersion "35.0.0"
    
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 35
        // ... 其他配置
    }
}

理解其中的区别：

compileSdkVersion：你的应用所编译针对的 Android API 级别（就像你的应用所"说"的"语言版本"）
targetSdkVersion：你的应用所设计和测试的 Android 版本（告诉 Android 如何对待你的应用）

步骤四：清理你的项目

在重新构建之前，你需要清除可能与新的 Android 15 配置冲突的旧构建产物。这就像在开始一个新项目前清理你的工作空间一样。

运行 NativeScript 清理命令：

bash 复制代码

ns clean

此命令将移除：

platforms 文件夹（包含特定于平台的生成代码）
构建缓存文件
临时编译产物

你也可以顺便清理你的 npm 缓存：

bash 复制代码

npm cache clean --force

步骤五：重建你的项目

现在是时候使用新的 Android 15 配置来重建你的项目了。根据你的工作流程，你有两个选择：

构建一个简单的应用包：

bash 复制代码

ns build android

构建并在连接的设备或模拟器上运行：

bash 复制代码

ns run android

后台发生了什么：NativeScript 现在正使用你新的 SDK 35 版本设置重新生成 Android 平台，下载必要的 Android 库，并使用更新后的 Android 运行时来编译你的 JavaScript 代码。

步骤六：在真实设备上测试

这是最重要的一步------在真实的 Android 设备上测试你的应用。模拟器很有帮助，但真实设备会暴露出模拟环境中不会出现的问题。
测试清单：

基本功能：浏览你应用的主要功能
权限：确保相机、位置和存储权限能正常工作
性能：检查是否有新的卡顿或内存问题
UI 元素：验证按钮、表单和布局正确显示
设备特定功能：测试生物识别认证等功能（如果适用）

故障排除小贴士

如果构建失败：

检查你的 Android SDK：确保你已通过 Android Studio 安装了 Android SDK 35
验证 Java 版本：Android 15 需要 Java 11 或更高版本
检查插件兼容性：一些第三方插件可能还不兼容 Android 15

如果你的应用行为异常：

查看更新日志：查阅 NativeScript 8.9+ 的发行说明，了解破坏性变更
更新插件：确保你所有的 NativeScript 插件都与 8.9+ 版本兼容
查阅 Android 15 行为变更：一些 Android API 在 Android 15 中的行为可能有所不同

未来升级的最佳实践

定期更新：不要在两次 Android 版本升级之间等待太久
增量测试：在单独的分支中升级并在合并前彻底测试
文档记录：记下任何需要更新的自定义配置
插件维护：定期更新你的 NativeScript 插件

小结

升级到 Android 15 可以确保你的 NativeScript 应用跟上最新的 Android 功能和安全要求。虽然这个过程涉及多个步骤，但遵循本指南进行系统操作将帮助你顺利地完成升级。

记住，这次升级不仅仅是为了合规------更是为了在你的 Android 设备上为用户提供最佳体验。Android 15 所改进的安全性、性能和功能集将让你作为开发者和你的应用用户都受益。

如何为 NativeScript 项目设置 Android 目标 API 级别

Google 开始要求在 Play Store 上发布的应用必须使用 API 30 或更高版本进行构建。以下是我为现有 NativeScript 项目设置 Android 目标 API 级别的快速指南。

从 2021 年 8 月开始，Google 开始强制要求所有新发布的应用必须以 API 30（Android 11）或更高版本为目标。这项变更的原因是为了带来显著的安全性和性能提升，并全面改善 Android 的用户体验。更多详细信息可以在下面的链接中找到：

https://developer.android.com/distribute/best-practices/develop/target-sdk

默认情况下，NativeScript 的目标 API 级别是 29（Android 10）。如果你在 2021 年 8 月之后尝试上传你的应用，Play Console 会开始抱怨 API 级别问题：

你的应用目前的目标 API 级别为 29，必须至少达到 API 级别 30，以确保它是基于为安全性和性能优化的最新 API 构建的。请将你的应用目标 API 级别至少设置为 30。

------ Google Play Console

如何设置 Android 目标 API 级别

你的应用目前的目标 API 级别为 29，必须至少达到 API 级别 30，以确保它是基于为安全性和性能优化的最新 API 构建的。请将你的应用目标 API 级别至少设置为 30。

好的，那怎么设置 Android 目标 API 级别呢？查看下面的解决方案。

解决方案

可以通过在 App_Resources/Android/app.gradle 文件中进行设置来轻松更改目标 SDK（API 级别）。在 android > defaultConfig 部分添加 targetSdkVersion 30，这会告诉 Gradle 使用你期望的配置来构建项目。最终的 app.gradle 内容应该看起来像这样（如果你有自定义配置，可能会有所不同）：

gradle 复制代码

android {
  defaultConfig {
    minSdkVersion 22
    generatedDensities = []
    targetSdkVersion 30
  }
  aaptOptions {
    additionalParameters "--no-version-vectors"
  }
}

设置完上述配置后，再次使用以下命令构建你的应用包：

bash 复制代码

ns build android ... --aab

你现在的新应用包的目标 API 级别应该是 30，并且可以准备上传到 Play Store 了。

附注

Gradle 是 Android 项目的构建工具，通常我们可以在 Android Studio 的界面中设置目标 SDK。然而，对于 NativeScript 来说，因为它有自己的 gradle 构建脚本，所以我们需要在 App_Resources 文件夹下的 app.gradle 中设置自己的配置，这个文件稍后会以某种方式与 NativeScript 的 gradle 脚本合并。我不确定这些配置具体是在哪里被读取或覆盖的。

好的，这是这篇文章的中文翻译：

Android Compile SDK 与 Target SDK：理解它们的区别

在进行 Android 开发时，你经常会遇到 build.gradle 文件中的两个重要配置值：compileSdkVersion 和 targetSdkVersion。尽管开发者通常会在新的 Android SDK 版本发布时同时更新这两个值，但理解它们各自不同的作用对于正确的应用开发和兼容性至关重要。

什么是 compileSdkVersion？

你可以把 compileSdkVersion 想象成 Gradle 用来构建你的应用程序的"工具箱"。它决定了在编译过程中将使用哪个版本的 Android SDK。

工作原理：

假设你想使用 Android 12 的新启动画面 API（SDK 版本 31）。这个 API 提供了内置的启动画面功能，你可以使用特定属性对其进行自定义。要使用这个功能，你需要：

在 Android Studio 中下载 SDK 版本 31
在你的 gradle 文件中将 compileSdkVersion 更新为 31

gradle 复制代码

android {
    compileSdkVersion 31
    // 其他配置...
}

那旧设备怎么办？

这里变得有趣起来。仅仅因为你使用 SDK 31 进行编译，并不意味着你就放弃了使用旧版 Android 的用户。如果你的 minSdkVersion 设置得低于 31，你就需要为无法访问新 API 的设备提供备用的实现方案。

当你更新 compileSdkVersion 时，可能会在编译期间遇到警告和错误。这是因为：

某些方法或属性在新 SDK 版本中已被弃用。
某些功能可能已被完全移除。
新 API 需要妥善处理向后兼容性。

重要提示 ：仅更改 compileSdkVersion 并不会实际改变你的应用行为------它只是在开发过程中为你提供了对新 API 和工具的访问权限。

什么是 targetSdkVersion？

如果说 compileSdkVersion 是你的工具箱，那么 targetSdkVersion 就是你对 Android 系统的一个"承诺"。它告诉系统，你的应用是为哪个 Android 版本设计和测试的。

工作原理：

当用户在高于你 targetSdkVersion 的 Android 版本的设备上运行你的应用时，系统可能会应用向后兼容行为，以确保你的应用能像最初设计的那样继续工作。

现实例子：

Android 12 改变了自定义通知的外观。以前，你可以自由地使用整个通知区域，但现在 Android 12 为了统一性，会为所有自定义通知应用一个标准模板。

如果你的 targetSdkVersion 设置低于 31：

系统会认为你没有测试过新的通知行为。
它会使用旧格式显示通知，以防止显示问题。
你的应用会按预期继续工作。

只有在你将 targetSdkVersion 更新到 31 后，新的通知界面才会应用到你的应用上。

compileSdkVersion 和 targetSdkVersion 的关系

虽然这两个值有不同的用途，但它们密切相关。

关键规则：

targetSdkVersion 不可以高于 compileSdkVersion。

这在逻辑上说得通------你不能去"瞄准"在编译时都无法访问的功能。

最佳实践：

理想情况下，compileSdkVersion 和 targetSdkVersion 应该相等，并指向最新的 SDK 版本。但前提是必须经过彻底的测试，以确保该版本引入的所有变更都能与你的应用平稳配合。

对 NativeScript 开发者的实际影响

对于 NativeScript 开发者来说，理解这些概念很重要，因为：

插件兼容性：原生插件需要与你的目标 SDK 版本兼容。
平台特定功能：当通过 NativeScript 访问原生 Android API 时，你需要考虑 SDK 版本的兼容性。
应用商店要求：Google Play 商店对目标 SDK 版本有要求，这会影响应用的更新和新提交。

总结

compileSdkVersion：用于编译你的应用的 Android SDK 版本（你的开发工具箱）。
targetSdkVersion：你的应用所设计面向的 Android 版本（你的兼容性承诺）。

这两个值对于处理 Android 兼容性都很重要，但在确保你的应用能在不同 Android 版本上正确运行方面扮演着不同的角色。在更新这些值时，务必进行彻底的测试。请记住，虽然你可以使用最新的 SDK 进行编译，但只有在确认你的应用能与该版本引入的任何新行为良好配合后，才能将其设为目标。