小墨の博客

minSdkVersion，targetSdkVersion，maxSdkVersion

首先先上官方文档链接：https://developer.android.com/guide/topics/manifest/uses-sdk-element.html?hl=zh-cn#ApiLevels

注意这个文档需要挂梯子才可以访问

下面摘录一下，摘录时间：2023.10.22

Google Play 会利用在您的应用清单中声明的 <uses-sdk> 属性，从不符合其平台版本要求的设备上滤除您的应用。在设置这些属性前，请确保您了解 Google Play 过滤器。

• 语法：

• <uses-sdk android:minSdkVersion="integer"
            android:targetSdkVersion="integer"
            android:maxSdkVersion="integer" />

• 包含于：

• <manifest>

• 说明：

• 您可以通过整数形式的 API 级别表示应用与一个或多个版本的 Android 平台的兼容性。应用表示的 API 级别将与给定 Android 系统的 API 级别进行比较，其结果在不同 Android 设备上可能有所差异。

  尽管名称如此，但该元素实际用于指定 API 级别，而非软件开发套件 (SDK) 或 Android 平台的版本号。API 级别始终是单个整数。您无法通过 API 级别关联的 Android 版本号来推知 API 级别。例如，API 级别不同于主要版本号，也不同于主要版本号与次要版本号之和。

  另请阅读有关对应用进行版本控制的文档。

• 属性：

• • android:minSdkVersion

  • 一个用于指定应用运行所需最低 API 级别的整数。如果系统的 API 级别低于该属性中指定的值，Android 系统将阻止用户安装应用。请始终声明该属性。

    注意：如果您不声明该属性，系统将假定默认值为“1”，这表示您的应用兼容所有 Android 版本。如果值不为“1”，并且您没有声明正确的 minSdkVersion，如果应用安装在具有不兼容 API 级别的系统上，则当应用在运行时尝试访问不可用的 API 时，会发生崩溃。因此，请务必在 minSdkVersion 属性中声明合适的 API 级别。

  • android:targetSdkVersion

  • 一个用于指定应用的目标 API 级别的整数。如果未设置，其默认值与为 minSdkVersion 指定的值相等。

    该属性用于通知系统，您已针对目标版本进行了测试，并且系统不应通过启用任何兼容性行为，以保持您的应用与目标版本的向前兼容性。应用仍可在较低版本上运行（最低版本为 minSdkVersion）。

    Android 会随新版本的推出而逐渐发展，在此过程中，某些行为乃至外观可能会发生变化。 不过，如果平台的 API 级别高于应用 targetSdkVersion 所声明的版本，系统便可启用兼容性行为，以便应用继续以您所期望的方式工作。您可以将 targetSdkVersion 指定为符合应用所运行平台的 API 级别，从而停用此类兼容性行为。

    例如，如果将该值设为“11”或更高，则系统会在应用运行在 Android 3.0 或更高版本上时对其应用 Holo 默认主题，还会在应用运行在更大屏幕上时停用屏幕兼容性模式（因为如果应用支持 API 级别 11，则表明其支持更大的屏幕）。

    系统可根据您为该属性设置的值启用许多兼容性行为。Build.VERSION_CODES 参考资料中的相应平台版本介绍了其中几种行为。

    如要让应用与各 Android 版本保持同步，请增加该属性的值，使其与最新的 API 级别保持一致，然后在相应平台版本上对应用进行全面测试。

    引入至：API 级别 4

  • android:maxSdkVersion

  • 一个用于指定应用运行所需最高 API 级别的整数。

    
    

    在 Android 1.5、1.6、2.0 及 2.0.1 中，系统会在安装应用时，以及系统更新后重新验证应用时检查该属性的值。无论是哪种情况，如果应用的 maxSdkVersion 属性低于系统本身使用的 API 级别，则系统将不允许安装应用。如果是系统更新后对应用进行重新验证，则实际上相当于从设备中移除应用。

    为说明该属性在系统更新后对应用的影响，请查看以下示例：

    Google Play 上发布了一个在其清单中声明 maxSdkVersion="5" 的应用。某位用户在运行 Android 1.6（API 级别 4）的设备上下载并安装了该应用。几周后，这位用户收到 Android 2.0（API 级别 5）的无线系统更新。安装更新后，系统检查该应用的 maxSdkVersion 并顺利对其完成重新验证。

    应用仍可照常运行。不过，一段时间后，设备再次收到系统更新，这次是更新到 Android 2.0.1（API 级别 6）。完成更新后，系统无法再重新验证应用，因为此时系统本身的 API 级别 (6) 已超过该应用支持的最高级别 (5)。系统会使该应用对用户不可见，实际上相当于将应用从设备上删除。

    警告：建议不要声明该属性。首先，既然新版 Android 平台已经发布了，那么便没有必要通过设置该属性，使其成为阻止您的应用部署至新版 Android 平台的一种手段。从设计上来讲，新版平台完全可以向后兼容。只要您的应用仅使用标准 API 并遵循部署最佳实践，就能在新版平台上正常运行。 其次，在某些情况下，声明该属性可能会导致您的应用在系统更新至更高 API 级别后从用户设备中移除。大多数可能安装您应用的设备都会定期收到无线系统更新，因此您应在设置该属性前考虑这些更新对应用的影响。

    引入至：API 级别 4

    某些 Android 版本（Android 2.0.1 之后的版本）在安装或重新验证时不会检查或强制执行 maxSdkVersion 属性。不过，在向用户呈现可供下载的应用时，Google Play 会继续将该属性用作过滤条件。

• 引入至：

• API 级别 1

什么是 API 级别？

API 级别是对 Android 平台版本提供的框架 API 修订版本进行唯一标识的整数值。

Android 平台提供一种框架 API，应用可利用它与底层 Android 系统进行交互。该框架 API 由以下部分组成：

• 一组核心软件包和类

• 一组用于声明清单文件的 XML 元素和属性

• 一组用于声明和访问资源的 XML 元素和属性

• 一组 intent

• 一组应用可请求的权限，以及系统中包括的权限强制执行

Android 平台的每个后续版本均可包括其提供的 Android 应用框架 API 的更新。

框架 API 的更新是为了让新 API 与早期版本的 API 保持兼容。换言之，大多数 API 更改都是新增更改，并且会引入新功能或替代功能。在 API 的某些部分得到升级时，系统会废弃经替换的旧版部分，但不会将其移除，以便其仍可供现有应用使用。

在极少数情况下，系统可能会修改或移除 API 的某些部分，但通常只有在支持 API 稳健性以及应用或系统安全性时，才需要进行此类更改。所有其他来自早期修订版的 API 部分都将继续保留，不做任何修改。

系统会使用名为“API 级别”的整数标识符来指定 Android 平台提供的框架 API。每个 Android 平台版本恰好支持一个 API 级别，但隐含对所有早期 API 级别（低至 API 级别 1）的支持。Android 平台初始版本提供的是 API 级别 1，后续版本的 API 级别则依次增加。

下表列出了各 Android 平台版本所支持的 API 级别。如需了解运行各版本的设备的相对数量，请参阅分发信息中心。

API 级别在 Android 中的使用

在帮助确保尽可能为用户和应用开发者提供最佳体验方面，API 级别标识符发挥着重要作用：

• 可让 Android 平台描述其支持的最高框架 API 修订版本。

• 可让应用描述自身所需的框架 API 修订版本。

• 可让系统协商在用户的设备上安装应用，从而不安装非兼容版本的应用。

每个 Android 平台版本都将其 API 级别标识符存储在 Android 系统自身内部。

应用可利用框架 API 提供的清单元素 (<uses-sdk>) 来说明其可运行的最低和最高 API 级别，以及所支持的首选 API 级别。该元素具有以下三个重要属性：

• android:minSdkVersion：能够运行应用的最低 API 级别。默认值为“1”。

• android:targetSdkVersion：运行应用的目标 API 级别。在某些情况下，这允许应用使用在目标 API 级别定义的清单元素或行为，而不是受限于仅使用针对最低 API 级别定义的清单元素或行为。

• android:maxSdkVersion：能够运行应用的最高 API 级别。重要提示：在使用此属性之前，请先阅读本页中有关此属性的信息。

例如，如要指定应用运行所需的最低系统 API 级别，应用需在其清单中加入带 android:minSdkVersion 属性的 <uses-sdk> 元素。android:minSdkVersion 的值是一个整数，对应能够运行应用的最低版本 Android 平台的 API 级别。

当用户试图安装应用，或在系统更新后重新验证应用时，Android 系统会先检查应用清单中的 <uses-sdk> 属性，然后将这些属性的值与它自己的内部 API 级别进行对比。只有在符合以下条件时，系统才允许开始安装：

• 如果声明 android:minSdkVersion 属性，则其值小于或等于系统的 API 级别整数。如果未声明，系统会假定应用需要 API 级别 1。

• 如果声明 android:maxSdkVersion 属性，则其值大于或等于系统的 API 级别整数。 如果未声明，则系统假定应用没有最高 API 级别。如需了解有关系统如何处理该属性的详细信息，请参阅此属性的说明。

如果在应用清单中进行声明，则 <uses-sdk> 元素的内容可能如下所示：

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

应用在 android:minSdkVersion 中声明 API 级别的主要原因是，告知 Android 系统，其使用在指定 API 级别引入的 API。

如果应用以某种方式安装在 API 级别较低的平台上，则它会在运行时试图访问不存在的 API 时发生崩溃。如果应用所需的最低 API 级别高于目标设备上平台版本的 API 级别，则系统不允许安装该应用，以防出现这种结果。

开发注意事项

下文提供您在开发应用时需要考虑的 API 级别的相关信息。

应用向前兼容性

Android 应用一般向前兼容新版 Android 平台。

由于几乎所有对框架 API 的更改都是新增更改，所以使用 API 任何给定版本（其 API 级别所指定版本）开发的 Android 应用均向前兼容更新版本的 Android 平台以及更高 API 级别。应用可在所有后续版本的 Android 平台上运行，除非在个别情况下，系统后来因某种原因将应用使用的某个 API 部分移除。

向前兼容性非常重要，因为许多 Android 设备都会接收无线 (OTA) 系统更新。用户可能会安装您的应用并顺利使用，然后通过接收 OTA 更新升级到新版 Android 平台。安装更新后，应用会在新运行时版本的环境中运行，但此版本仍包含应用所依赖的 API 和系统功能。

在该 API 之下所做的更改（例如对底层系统本身的更改）可能会影响在新环境中运行的应用。作为应用开发者，您必须了解应用在各系统环境中的外观和行为。

为帮助您在各种版本的 Android 平台上测试应用，Android SDK 提供多个可供下载的平台。每个平台均包含兼容的系统映像，您可通过在 AVD 中运行该映像来测试应用。

应用向后兼容性

Android 应用未必向后兼容比其编译时所用目标版本更旧的那版 Android 平台。

每个新版 Android 平台都可包含新的框架 API，例如能让应用访问新平台功能或替换现有 API 部分的 API。在新平台上运行时，应用可以使用这些新 API；在更新版本的平台（API 级别所指定的平台）上运行时，应用也可使用这些新 API。但是，由于早期版本的平台未包含新 API，因此使用新 API 的应用无法在这些平台上运行。

尽管 Android 设备不太可能降级到先前版本的平台，但您必须认识到，可能有许多设备运行的是早期版本的平台。即便是在接收 OTA 更新的设备中，有些设备的更新也可能会滞后，而且可能在相当长的时间内无法接收更新。

选择平台版本和 API 级别

在开发应用时，您可以选择编译应用所用的平台版本。一般而言，根据应用所支持平台的最低版本编译应用。

您可以在编译应用时依次降低其使用的目标 build，从而确定可能的最低平台版本。确定最低版本后，使用相应平台版本和 API 级别创建 AVD，然后对应用进行全面测试。请务必在应用的清单中声明 android:minSdkVersion 属性，并将其值设置为平台版本的 API 级别。

声明最低 API 级别

构建应用时，如果您使用最新平台版本中引入的 API 或系统功能，则将 android:minSdkVersion 属性设置为最新平台版本的 API 级别。这样，用户只能在运行兼容版 Android 平台的设备上安装您的应用，进而确保您的应用可以在用户设备上正常工作。

如果您的应用使用最新平台版本中引入的 API，但未声明 android:minSdkVersion 属性，则该应用可在运行最新版平台的设备上正常工作，但无法在运行早期版平台的设备上正常工作。在后一种情况下，当在运行时试图使用早期版本上不存在的 API 时，应用会发生崩溃。

针对更高 API 级别进行测试

编译应用之后，请确保在应用的 android:minSdkVersion 属性所指定的平台上对其进行测试。为此，请使用您应用所需的平台版本创建 AVD。此外，为检查向前兼容性，请在所有 API 级别高于您应用 API 级别的平台上运行并测试您的应用。

Android SDK 提供多个可供您使用的平台版本（包括最新版本），以及可供您在必要时下载其他平台版本的更新器工具。

如要访问该更新器，请使用位于 <sdk>/tools 目录的 android 命令行工具。您可以通过执行 android sdk 来启动 SDK 更新器。您也可以双击 android.bat (Windows) 或 android (OS X/Linux) 文件。

如要在模拟器中的不同平台版本上运行应用，请为您想测试的每个平台版本创建 AVD。如需了解有关 AVD 的详细信息，请参阅创建和管理虚拟设备。如要使用实体设备进行测试，请确保您知晓其所运行 Android 平台的 API 级别。请参阅本文表格中所列的平台版本及其 API 级别。

按 API 级别过滤参考文档

每个 Android 平台参考文档页面的左上角都有一个“API 级别”控件。利用该控件，您可根据应用在其清单文件的 android:minSdkVersion 属性中指定的 API 级别，只显示该应用实际可访问 API 部分的对应文档。

如需使用过滤功能，请从菜单中选择您的应用指定的 API 级别。后期 API 级别中引入的 API 随即会灰显，并且系统会屏蔽其内容，因为您的应用将无法访问它们。

在文档中按 API 级别进行过滤并不会显示各 API 级别新增或引入的 API。它只是提供一种方式，供用户查看与给定 API 级别关联的整个 API，但会将后续 API 级别中引入的 API 元素排除在外。

如需返回查看完整文档，请选择 API 级别菜单顶部的 REL。默认情况下，API 级别过滤功能处于停用状态，因此无论 API 级别为何，您都能查看完整的框架 API。

各 API 元素的参考文档指定引入各元素的 API 级别。各文档页面内容区域的右上角会以“在 API 级别中引入”的形式指定软件包和类的 API 级别。位于右边距处的详细说明标头中会指定类成员的 API 级别。

张小弟之家