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

对于你的 Kotlin Maven 项目, 除默认的 Maven Central 仓库之外, 可以配置 Maven 查找 artifact 的位置, 还可以定义你的项目所依赖的库.

声明仓库

默认情况下, 所有 Maven 项目都可以使用 mavenCentral 仓库. 要访问其他仓库中的 artifact, 请在 <repositories> 节中, 为仓库名称指定自定义 ID 和 URL:

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

通常, 要添加对某个库的依赖项, 你应该在 <dependencies> 节中声明一个新的 <dependency> 条目:

<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 依赖项, 例如使用了不同的版本, Kotlin Maven plugin 的 <extensions> 不会覆盖它.

你也可以关闭标准库的自动添加. 方法是, 在 <properties> 节中添加以下内容:

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

手动配置

要手动将 Kotlin 标准库添加到你的项目, 请更新 pom.xml 文件中的 dependencies 节, 内容如下:

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlin</groupId>
        <artifactId>kotlin-stdlib</artifactId>
        <!-- 使用 <properties/> 中指定的 kotlin.version: -->
        <version>${kotlin.version}</version>
    </dependency>
</dependencies>

对测试库的依赖项

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

<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 库, 你可以添加基础 artifact 名, 或带有 -jvm 后缀的 artifact 名. 请参考 klibs.io 库的 README 文件.

例如, 添加 kotlinx.coroutines 库的依赖项:

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

添加 kotlinx-datetime 库的依赖项:

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

使用 BOM 管理依赖项

物料清单(Bill of Materials, BOM) 是一种特殊的 POM 文件, 用于管理项目中的依赖项版本. 它可以使相关的 artifact 版本保持一致, 并避免版本冲突.

Kotlin 发布了 kotlin-bom artifact, 它指定了对应于同一个 Kotlin 发布版的 Kotlin 库的版本, 例如 kotlin-stdlib, kotlin-reflect, 以及 kotlin-test. 当你的项目中的其他库具有 Kotlin artifact 的传递依赖项时, 这会很有用, 因为它可以确保所有的依赖项解析为相同的 Kotlin 版本.

要使用 Kotlin BOM, 请在你的 pom.xml 文件的 <dependencyManagement> 节中导入它, 方式如下:

<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 编译器

2026/10/11