配置发布变体

发布变体让您能够为用户创建更定制化的体验。配置发布变体可让您发布不同的构建变体，每个变体都有其自己的属性。

发布库的多个构建变体可让用户根据其需求选择相应的功能。例如，您可以为调试与发布构建类型发布不同的工件。调试发布工件可能包含额外的日志记录代码和不同的依赖项，以启用此额外的日志记录功能。

在继续之前，请确保您已准备好您的库以供发布。

使用 Gradle 模块元数据

为了发布库的变体，您必须使用Gradle 模块元数据 (GMM)。GMM 描述了您的发布内容并维护变体感知型依赖项管理。GMM 默认随您的库一起发布。

使用 GMM 的优势包括

• 如果您使用 Gradle 6.0 或更高版本以及 GMM，您可以发布多个发布变体或多个工件，每个都拥有自己的属性和依赖项。如果您使用 Maven 的 POM 文件而不是 GMM，则只能发布一个工件。如果您使用 POM 文件，可以使用分类器发布其他工件，但这些额外的工件不能有自己的依赖项。
• Gradle 会自动为编译和运行时各创建一个变体，每个变体都有自己的依赖项。您可能为编译发布一个变体，为运行时发布另一个变体，以便消费者可以根据其使用库的时机进行选择。GMM 允许消费者根据已发布库对 api、implementation 或 compileOnly/runtimeOnly 的使用情况，查看编译和运行时的不同依赖项。如需查看完整的依赖项列表，请参阅依赖项配置。即使您只发布一个发布变体，此功能也可用。
• 使用测试工具时，您可以发布一个附加变体，其中包含特殊元数据或功能，以便消费者可以选择该变体。即使您只发布一个发布变体，此功能也可用。

了解发布变体

要了解发布变体的工作原理，熟悉 Gradle 的基本发布步骤会很有帮助。以下是一些发布关键概念

• 构建变体：Gradle 用于构建您的库的配置，它是构建类型和产品风味的交叉乘积。如需了解详情，请参阅Android 构建术语表。
• 工件：构建生成的文件或目录。在库发布的上下文中，工件通常是 JAR 或 AAR 文件。
• 发布变体：具有其关联属性、功能和依赖项的工件。请注意，Gradle 将发布变体称为变体。但是，在这些文档中，它们被称为发布变体，以区别于构建变体。
• 属性：当有多个选项时，Gradle 使用属性来识别和选择发布变体。例如，org.gradle.usage=java-api 和 org.gradle.jvm.version=11 是变体属性。
• 软件组件：一个 Gradle 对象，可以包含一个或多个发布变体，并发布到一组 Maven 坐标 (groupdId:artifactId:version)。它通过 Project.getComponents() 在 Gradle 的 DSL 中公开。
• 发布内容：发布到仓库并供消费者使用的内容。发布内容由一个软件组件及其元数据（例如其身份 groupId:artifactId:version）组成。

Android Gradle 插件 (AGP) 7.1 引入了一种领域特定语言 (DSL)，用于控制在发布期间使用哪些构建变体以及忽略哪些构建变体。该 DSL 允许您创建包含以下任何内容的 SoftwareComponent 实例

• 来自一个构建变体的一个发布变体
• 来自多个构建变体的多个发布变体

当创建包含多个发布变体的软件组件时，AGP 会在每个变体上设置属性，以便消费者可以选择所需的相应变体。这些属性直接来源于用于创建构建变体的构建类型和风味。创建只包含一个发布变体的组件不需要属性，因为无需区分。

创建包含单个发布变体的软件组件

以下代码片段配置了一个软件组件，该组件包含一个从 release 构建变体创建的发布变体，并将源 JAR 作为次要工件添加

android {
  publishing {
    singleVariant("release") {
        withSourcesJar()
    }
  }
}

android {
  publishing {
    singleVariant('release') {
        withSourcesJar()
    }
  }
}

您可以创建多个组件，每个组件都包含一个发布变体，并将其发布到不同的 Maven 坐标下。在这种情况下，发布变体上不设置属性。通过查看发布元数据，您无法判断此发布变体是否来自 release 构建变体。由于只涉及一个发布变体，因此无需进行消歧。

创建包含多个发布变体的软件组件

您可以选择所有或部分构建变体放入单个软件组件中。AGP 会自动使用构建类型名称、产品风味名称和产品风味维度名称来创建属性，以便使用项目可以区分它们。

要在单个组件中发布所有构建变体，请在模块级 build.gradle 文件中的 multipleVariants{} 块中指定 allVariants()

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

这会创建一个名为 default 的组件。要为组件指定其他名称，请使用 multipleVariants({name})。在这种情况下，所有构建类型和产品风味维度都用作属性。

您还可以使用 includeBuildTypeValues() 和 includeFlavorDimensionAndValues() 来选择要发布的变体

android {
  publishing {
    multipleVariants("custom") {
      includeBuildTypeValues("debug", "release")
      includeFlavorDimensionAndValues(
        dimension = "color",
        values = arrayOf("blue", "pink")
      )
        includeFlavorDimensionAndValues(
          dimension = "shape",
          values = arrayOf("square")
      )
    }
  }
}

android {
  publishing {
    multipleVariants('custom') {
      includeBuildTypeValues('debug', 'release')
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'color',
        /*values =*/ 'blue', 'pink'
      )
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'shape',
        /*values =*/ 'square'
      )
    }
  }
}

在此示例中，自定义组件包含构建类型的 (debug, release) 所有组合，维度 color 的 (blue, pink) 组合，以及维度 shape 的 (square) 组合。

所有风味维度都必须列出，即使您只发布一个维度的一个值，这样 AGP 才能知道每个维度要使用哪个值。

下表列出了生成的发布变体及其关联属性。

实际上，会发布更多的变体。例如，上述每个变体都会发布两次，一次用于编译，一次用于运行时，它们具有不同的依赖项（取决于声明的依赖项是使用 implementation 还是 api），并且属性 org.gradle.Usage 的值也不同。但是，这两个变体的工件（AAR 文件）是相同的。

如需了解详情，请参阅 publishing API 文档。

发布多风味库的兼容性问题

使用 AGP 7.0 或更低版本的项目无法使用 AGP 7.1 或更高版本发布的多风味库。这是一个已知问题，原因是 AGP 7.1 中产品风味维度的属性名称从 dimensionName 更改为 com.android.build.api.attributes.ProductFlavor:dimensionName。根据您的项目设置，您可以使用旧版变体 API 中的 missingDimensionStrategy 来解决此问题。

例如，假设您的应用项目只有一个版本产品风味维度

android {
    applicationVariants.forEach { variant ->
        val flavor = variant.productFlavors[0].name
        val attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        val dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}

android {
    applicationVariants.forEach { variant ->
        def flavor = variant.getProductFlavors()[0].name
        def attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        def dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}