11.2.3 在 Maven 项目中设置仓库和依赖

  3 分钟阅读  

原文链接: https://kotlinlang.org/docs/maven-set-dependencies.html

11.2.3 在 Maven 项目中设置仓库和依赖

对于你的 Kotlin Maven 项目，你可以配置 Maven 在默认的 Maven Central 仓库之外还要去哪里查找产物，并定义项目所依赖的库。

声明仓库

默认情况下，所有 Maven 项目都可使用 mavenCentral 仓库。要访问其他仓库中的产物，请在 <repositories> 部分为仓库名称指定一个自定义 ID，并给出它的 URL：

1
2
3
4
5
6

<repositories>
    <repository>
        <id>spring-repo</id>
        <url>https://repo.spring.io/release</url>
    </repository>
</repositories>

注意： 如果你在 Gradle 项目中把 mavenLocal() 声明为仓库，则在 Gradle 和 Maven 项目之间切换时可能会遇到问题。更多信息请参阅声明仓库。

一般来说，要添加对某个库的依赖，你应在 <dependencies> 部分声明一个新的 <dependency> 条目：

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json</artifactId>
        <version>1.11.0</version>
    </dependency>
</dependencies>

设置依赖

对标准库的依赖

Kotlin 有一个内容丰富的标准库，你可以在应用中使用它。你可以手动添加标准库依赖，也可以启用 <extensions> 选项，在缺少它时自动配置。

自动配置

你可以使用 Kotlin Maven 插件提供的 <extensions> 选项来免除手动配置。如果项目中没有定义 kotlin-stdlib 依赖，它会自动添加。例如，在你创建新的 Kotlin Maven 项目，或把 Kotlin 引入已有的 Java Maven 项目时。

如果你已经声明了 kotlin-stdlib 依赖（例如使用了不同的版本），那么带 <extensions> 的 Kotlin Maven 插件不会覆盖它。

你也可以选择不自动添加标准库。为此，请在 <properties> 部分添加以下内容：

1
2
3
4
5

<project>
    <properties>
        <kotlin.smart.defaults.enabled>false</kotlin.smart.defaults.enabled>
    </properties>
</project>

注意： 该属性不仅会禁用标准库的自动添加，还会禁用源根路径的注册。其他 <extensions> 功能不受影响。

手动配置

要手动把 Kotlin 标准库添加到项目中，请用以下内容更新 pom.xml 文件中的 dependencies 部分：

1
2
3
4
5
6
7
8

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-stdlib</artifactId>

        <version>${kotlin.version}</version>
    </dependency>
</dependencies>

注意： 如果你面向 JDK 7 或 8，且 Kotlin 版本早于：* 1.8，请分别使用 kotlin-stdlib-jdk7 或 kotlin-stdlib-jdk8。* 1.2，请分别使用 kotlin-stdlib-jre7 或 kotlin-stdlib-jre8。

对测试库的依赖

如果你的项目使用 Kotlin 反射或测试框架，请添加相关依赖。反射库使用 kotlin-reflect，测试库使用 kotlin-test 和 kotlin-test-junit5：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-reflect</artifactId>
        <version>${kotlin.version}</version>
    </dependency>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-test-junit5</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

对 kotlinx 库的依赖

对于 kotlinx 库，你既可以添加基础产物名，也可以添加带 -jvm 后缀的名称。请参阅该库在 klibs.io 上的 README 文件。

例如，要添加对 kotlinx.coroutines 库的依赖：

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-coroutines-core</artifactId>
        <version>1.11.0</version>
    </dependency>
</dependencies>

要添加对 kotlinx-datetime 库的依赖：

1
2
3
4
5
6
7

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-datetime-jvm</artifactId>
        <version>0.8.0</version>
    </dependency>
</dependencies>

使用 BOM 管理依赖

物料清单（BOM）是一种特殊的 POM 文件，用于管理项目中的依赖版本。它能让相关的产物保持版本一致，并避免版本冲突。

Kotlin 发布了 kotlin-bom 产物，其中指定了与同一个 Kotlin 版本对应的各个 Kotlin 库的版本，例如 kotlin-stdlib、kotlin-reflect 和 kotlin-test。当项目中的其他库对 Kotlin 产物有传递依赖时，这很有用，因为它能确保所有依赖都解析到同一个 Kotlin 版本。

要使用 Kotlin BOM，请按如下方式在 pom.xml 文件的 <dependencyManagement> 部分导入它：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-bom</artifactId>
            <version>2.4.20</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

导入 BOM 之后，你就可以在 <dependencies> 部分声明 Kotlin 依赖而无需指定版本；版本会自动来自该 BOM 文件。

  • 导入 BOM 本身不会向项目添加任何依赖。它只控制显式声明和传递依赖的版本。
  • 如果你仍然为某个依赖指定了 <version>，该值会覆盖 BOM 中的版本。

如果你的项目发布了若干个一起发布的库，你可以提供自己的 BOM，让用户以同样的方式对齐这些库的版本。要了解如何编写自己的 BOM，请参阅 Maven 文档。

接下来做什么？

配置 Kotlin 编译器

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)