Kotlin 语言参考文档 中文版 Help

发布跨平台的库

你可以设置你的跨平台库, 发布到不同的位置:

发布到本地 Maven 仓库

你可以使用 maven-publish Gradle plugin, 将跨平台的库发布到本地的 Maven 仓库:

  1. 在 shared/build.gradle.kts 文件中, 添加 maven-publish Gradle plugin.

  2. 指定库的 group 和 version, 以及需要发布到的 仓库:

    plugins { // ... id("maven-publish") } group = "com.example" version = "1.0" publishing { repositories { maven { //... } } }

当与 maven-publish 一起使用时, Kotlin plugin 对在当前主机上能够构建的每个编译目标, 都会自动创建发布任务, Android 编译目标除外, 因为它需要 更多步骤来配置发布任务.

发布的结构

Kotlin Multiplatform 库的发布包括多个 Maven 发布, 每个对应于一个特定的目标平台. 此外, 还有一个包含全体的 根(Root) 发布, kotlinMultiplatform, 代表发布的整个库.

在添加为共通源代码集的 依赖项 时, 根发布会自动解析为正确的平台相关的 artifact.

目标平台相关的发布(Target-specific Publication)与根发布(Root Publication)

Kotlin Multiplatform Gradle plugin 会为每个编译目标配置单独的发布. 对于以下项目配置:

// projectName = "lib" group = "test" version = "1.0" kotlin { jvm() iosX64() iosArm64() }

这个设置会生成以下 Maven 发布:

目标平台相关的发布(Target-specific Publication)

  • 对于 jvm 目标: test:lib-jvm:1.0

  • 对于 iosX64 目标: test:lib-iosx64:1.0

  • 对于 iosArm64 目标: test:lib-iosarm64:1.0

每个目标平台相关的发布都是独立的. 例如, 运行 publishJvmPublicationTo<MavenRepositoryName> 只会发布 JVM 模块, 不会发布其他模块.

根发布(Root Publication)

kotlinMultiplatform 根发布: test:lib:1.0.

根发布充当一个入口点, 引用所有的目标平台相关的发布. 它包含元数据 artifact, 并通过包含其他发布的引用来确保正确的依赖关系解析: 各个平台 artifact 预期的 URL 和座标(coordinate).

  • 有些仓库, 比如 Maven Central, 要求 root 模块包含不带分类标识的 JAR artifact, 比如 kotlinMultiplatform-1.0.jar. Kotlin Multiplatform plugin 会自动产生需要的 artifact, 以及内嵌的元数据 artifact. 也就是说, 你不需要向你的库的 root 模块添加一个空的 artifact, 来满足仓库的要求.

  • 如果仓库要求, kotlinMultiplatform 发布还可能会需要源代码和文档的 artifact. 这种情况下, 请在 publication 内使用 artifact().

发布一个完整的库

要一次性发布所有必须的 artifact, 请使用 publishAllPublicationsTo<MavenRepositoryName> 总体任务. 例如:

./gradlew publishAllPublicationsToGithubPackagesRepository

发布到 Maven Local 时, 你可以使用专用的 task:

./gradlew publishToMavenLocal

这些 task 会确保所有的目标平台相关的发布和根发布都在一起发布, 使得库在依赖解析时完整可用.

或者, 你也可以使用单独的发布 task. 首先运行根发布:

./gradlew publishKotlinMultiplatformPublicationToMavenLocal

这个 task 会发布一个 *.module 文件, 包含目标平台相关的发布的信息, 但目标平台本身还没有发布. 要完成发布过程, 请分布发布各个目标平台相关的发布:

./gradlew publish<TargetName>PublicationToMavenLocal

这样就可以确保所有 artifact 可用, 并且正确的引用.

对主机的要求

Kotlin/Native 支持交叉编译(cross-compilation), 可以在任何主机上生成必要的 .klib artifact. 但是, 还是有一些细节问题你需要注意.

针对 Apple 目标平台的编译

要对 Apple 目标平台的项目生成 artifact, 你通常需要 Apple 机器. 但是, 如果你希望使用其它主机, 请在你的 gradle.properties 文件中设置这个选项:

kotlin.native.enableKlibsCrossCompilation=true

交叉编译(cross-compilation) 目前是实验性功能, 存在一些限制. 对于以下情况, 你仍然需要使用 Mac 机器:

重复发布

为了避免发布期间发生问题, 应该只从一个主机发布所有的 artifact, 以免在仓库中重复发布. 例如, Maven Central, 明确禁止重复发布, 并会让发布过程失败.

发布 Android 库

要发布一个 Android 库, 需要一些额外的配置.

默认情况下, 没有任何 Android 库的 artifact 会发布. 要发布一组 Android 构建变体(variant) 生成的 artifact, 需要在 shared/build.gradle.kts 文件的 Android 编译目标代码段内指定编译变体名称:

kotlin { androidTarget { publishLibraryVariants("release") } }

上面的示例适用于没有 产品风格(Product Flavor) 的 Android 库. 对于存在产品风格(Product Flavor)的库, 编译变体名称还需要包含产品风格名称, 比如 fooBarDebug 或 fooBarRelease.

默认的发布设置如下:

  • 如果发布的编译变体是相同的构建类型 (比如, 都是 release 或 debug), 那么它们将兼容任意的使用者构建类型.

  • 如果发布的编译变体是不同的构建类型, 那么只有 release 变体兼容于与发布的编译变体不同的使用者构建类型. 所有的其他编译变体 (比如 debug) 只会与使用者的相同构建类型匹配, 除非使用者项目指定了 匹配回退(Matching Fallback).

如果你希望让所有发布的 Android 变体都只兼容于库的使用者的相同构建类型, 请设置 Gradle 属性: kotlin.android.buildTypeAttribute.keep=true.

也可以将各个编译变体以产品风格为单位分组发布, 使得不同的编译类型的输出文件可以放在同一个模块内, 编译类型成为 artifact 中的一个分类符 (release 编译类型的结果发布时仍然不带分类符). 这种发布模式默认是关闭的, 如果要启用, 请在 shared/build.gradle.kts 文件中使用以下设置:

kotlin { androidTarget { publishLibraryVariantsGroupedByFlavor = true } }

禁用源代码的发布

Kotlin Multiplatform Gradle plugin 默认会对所有指定的编译目标发布源代码. 但是, 你可以在 shared/build.gradle.kts 文件中使用 withSourcesJar() API 配置并禁用源代码发布:

  • 对所有的编译目标禁用源代码发布:

    kotlin { withSourcesJar(publish = false) jvm() linuxX64() }

  • 只对指定的编译目标禁用源代码发布:

    kotlin { // 只对 JVM 禁用源代码发布: jvm { withSourcesJar(publish = false) } linuxX64() }

  • 对指定的编译目标之外的所有编译目标禁用源代码发布:

    kotlin { // 对 JVM 之外的所有编译目标禁用源代码发布: withSourcesJar(publish = false) jvm { withSourcesJar(publish = true) } linuxX64() }

禁用 JVM 环境属性的发布

从 Kotlin 2.0.0 开始, Gradle 属性 org.gradle.jvm.environment 会自动随所有的 Kotlin 变体一起发布, 以便帮助区分 Kotlin Multiplatform 库的 JVM 和 Android 变体. 这个属性指明哪个库变体适用于哪个 JVM 环境, Gradle 使用这个信息在你的项目中进行依赖项解析. 目标环境可以是 "android", "standard-jvm", 或 "no-jvm".

你可以禁用这个属性的发布, 方法是向你的 gradle.properties 文件添加以下 Gradle 属性:

kotlin.publishJvmEnvironmentAttribute=false

推广你的库

你的库可以在 JetBrains 的检索平台 上展示. 它的目标是为了让使用者便利的根据目标平台查找 Kotlin Multiplatform 库.

符合标准的库会被自动添加进来. 关于如何添加你的库, 详情请参见 FAQ.

下一步做什么

2025/08/04
构建最终的原生二进制文件iOS App 的隐私清单(Privacy Manifest)