12.1.4 Kotlin 编译器选项

  11 分钟阅读  

原文链接: https://kotlinlang.org/docs/compiler-reference.html

12.1.4 Kotlin 编译器选项

Kotlin 的每个版本都包含用于受支持目标的编译器：JVM、JavaScript，以及面向受支持平台的原生二进制文件。

这些编译器被以下场景使用：

  • 当你为 Kotlin 项目点击 Compile 或 Run 按钮时使用的 IDE。
  • 当你在控制台或 IDE 中调用 gradle build 时使用的 Gradle。
  • 当你在控制台或 IDE 中调用 mvn compile 或 mvn test-compile 时使用的 Maven。

你也可以按照使用命令行编译器教程中所述，从命令行手动运行 Kotlin 编译器。

编译器选项

Kotlin 编译器有许多用于定制编译过程的选项。本页按不同目标列出编译器选项，并附带每个选项的说明。

有几种方式可以设置编译器选项及其取值（编译器参数）：

  • 在 IntelliJ IDEA 中，在 Additional command line parameters 文本框中填写编译器参数，该文本框位于 Settings/Preferences | Build, Execution, Deployment | Compiler | Kotlin Compiler。
  • 如果你使用 Gradle，请在 Kotlin 编译任务的 compilerOptions 属性中指定编译器参数。详情请参见 Gradle 编译器选项。
  • 如果你使用 Maven，请在 Maven 插件节点的 <configuration> 元素中指定编译器参数。详情请参见 Maven。
  • 如果你运行命令行编译器，请把编译器参数直接添加到工具调用中，或写入 argfile。

例如：

1

  $ kotlinc hello.kt -include-runtime -d hello.jar

注意： 在 Windows 上，当你传入包含分隔符字符（空白、=、;、,）的编译器参数时，请用双引号（"）把这些参数括起来。$ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"

编译器选项的 Schema

所有编译器选项的通用 schema 以 JAR 制品的形式发布在 org.jetbrains.kotlin:kotlin-compiler-arguments-description 下。该制品既包含代码表示，也包含所有编译器选项描述（面向非 Kotlin 使用者）的 JSON 等价表示，还包括元数据，例如每个选项在哪个版本中引入或稳定。

通用选项

以下选项对所有 Kotlin 编译器都是通用的。

-api-version version

设置 API 版本，以控制你的代码在运行时可使用哪些 Kotlin API。例如，如果你使用 Kotlin 编译器 2.4.0 并设置 -api-version=2.1，那么你的代码仍与 Kotlin 标准库 2.1.0 兼容。

你不能把 -api-version 的值设置得高于 -language-version 的值。

在大多数情况下，API 版本和语言版本应当相同。一个例外是：当你要为必须运行旧版 Kotlin 标准库的使用者开发库时。在这种情况下，请设置较旧的 API 版本，以避免意外使用那些使用者无法使用的 API。

有关 API 版本如何影响兼容性的更多信息，请参见面向库作者的向后兼容性指南。

-help (-h)

显示用法信息并退出。只显示标准选项。要显示高级选项，请使用 -X。

-kotlin-home path

为 Kotlin 编译器指定自定义路径，用于发现运行时库。

-language-version version

设置语言版本，以控制编译期间可用的 Kotlin 语言特性。

例如，如果你想在不改变编译器行为的情况下享受新的编译性能改进，可以使用较新的编译器版本配合较旧的语言版本。使用较旧的语言版本时，你不能使用较新的语言特性，但也不会看到该版本之后引入的新错误和弃用。这种方式对需要与较旧 Kotlin 版本保持兼容的库作者特别有用。更多信息请参见面向库作者的向后兼容性指南。

你可以把最近三个稳定 Kotlin 版本之一配置为语言版本。例如，Kotlin 2.5.0 支持低至 2.2 的语言版本。

如果你使用较旧的语言版本，也需要使用较旧的 API 版本。更多信息请参见 。

提示： 从技术上讲，你可以配置较新的语言版本，以便在语言特性稳定之前试用它们。不过，最好按照各自的专门说明逐个启用特性。

-opt-in annotation

启用对带给定全限定名要求注解的、需要选择启用的 API 的使用。

-P plugin:pluginId:optionName=value

向 Kotlin 编译器插件传递一个选项。核心插件及其选项列在文档的核心编译器插件一节中。

-progressive

为编译器启用渐进模式。

在渐进模式下，针对不稳定代码的弃用和缺陷修复会立即生效，而不是经历一个平缓的迁移周期。以渐进模式编写的代码是向后兼容的；不过，以非渐进模式编写的代码在渐进模式下可能导致编译错误。

-script

对 Kotlin 脚本文件求值。使用该选项调用时，编译器会执行给定参数中的第一个 Kotlin 脚本（*.kts）文件。

-verbose

启用详细日志输出，其中包含编译过程的细节。

-version

显示编译器版本。

-X

实验性 - 通用

显示高级选项的信息并退出。这些选项目前不稳定：其名称和行为可能在不通知的情况下发生变化。

Kotlin 契约选项

实验性 - 通用

以下选项启用实验性的 Kotlin 契约特性。

-Xallow-contracts-on-more-functions

在更多声明中启用契约，包括属性访问器、特定运算符函数，以及对泛型类型的类型断言。

-Xallow-condition-implies-returns-contracts

允许在契约中使用 returnsNotNull() 函数，以便对指定条件假定返回非 null 值。

-Xallow-holdsin-contract

允许在契约中使用 holdsIn 关键字，以便在 lambda 内假定某个布尔条件为 true。

-Xallow-returns-result-of

允许使用 returnsResultOf() 契约，以便未使用返回值检查器能够区分可以忽略的结果与高阶函数的有意义结果。

-Xallow-reified-type-in-catch

实验性 - 通用

支持在 inline 函数的 catch 子句中使用具体化的 Throwable 类型参数。

-Xcollection-literals

实验性 - 通用

支持使用方括号语法 [] 的集合字面量。

-Xcompiler-plugin-order=

实验性 - 通用

配置编译器插件的运行顺序。编译器先运行 plugin.before，然后运行 plugin.after：

你可以为三个或更多插件定义多条排序规则。例如：

1
2

kotlinc -Xcompiler-plugin-order=plugin.first>plugin.middle
kotlinc -Xcompiler-plugin-order=plugin.middle>plugin.last

这会得到以下运行顺序：

  1. plugin.first
  2. plugin.middle
  3. plugin.last

如果某个编译器插件不存在，相应的规则会被忽略。

你可以按 ID 配置以下插件：

| 编译器插件 | 插件 ID |

| all-open、kotlin-spring | org.jetbrains.kotlin.allopen | | AtomicFU | org.jetbrains.kotlinx.atomicfu | | Compose | androidx.compose.compiler.plugins.kotlin | | js-plain-objects | org.jetbrains.kotlinx.jspo | | jvm-abi-gen | org.jetbrains.kotlin.jvm.abi | | kapt | org.jetbrains.kotlin.kapt3 | | Lombok | org.jetbrains.kotlin.lombok | | no-arg、kotlin-jpa | org.jetbrains.kotlin.noarg | | Parcelize | org.jetbrains.kotlin.parcelize | | Power-assert | org.jetbrains.kotlin.powerassert | | 带接收者的 SAM | org.jetbrains.kotlin.samWithReceiver | | 序列化 | org.jetbrains.kotlinx.serialization |

该运行顺序只控制编译器插件的后端，而不控制前端。

-Xdata-flow-based-exhaustiveness

实验性 - 通用

为 when 表达式启用基于数据流的穷尽性检查。

-Xexplicit-context-arguments

实验性 - 通用

为上下文参数启用显式的上下文实参。

这让你可以通过在调用处传入上下文实参来消除重载歧义。

-Xklib-ir-inliner

实验性 - 通用

配置是否对 Kotlin/Native、Kotlin/JS 和 Kotlin/Wasm 启用模块内内联。默认启用。

该选项支持以下模式：

  • disabled：对 Kotlin/Native、Kotlin/JS 和 Kotlin/Wasm 禁用模块内内联。
  • full：启用跨模块内联。

-Xintrinsic-const-evaluation

实验性 - 通用

启用改进的编译期常量。

-Xname-based-destructuring

实验性

配置编译器如何根据属性名解释解构声明。

该选项支持以下模式：

  • only-syntax：启用基于名称解构的显式形式，而不改变现有解构声明的行为。
  • name-mismatch：在数据类中使用基于位置的解构且变量名与属性名不匹配时报告警告。
  • complete：启用带圆括号的简短形式的基于名称解构，并继续支持带方括号语法的基于位置的解构。

-Xphases-to-dump-before

实验性 - 通用

把它设置为 ExternalPackageParentPatcherLowering 可在 IR lowering 编译阶段之后创建转储文件。使用 -Xdump-directory 编译器选项为 Kotlin/JVM 配置输出目录。

-Xrepl

实验性 - 通用

激活 Kotlin REPL。

1

kotlinc -Xrepl

-Xreturn-value-checker

实验性 - 通用

配置编译器如何报告被忽略的结果：

  • disable：禁用未使用返回值检查器（默认）。
  • check：启用检查器，并对已标记函数中被忽略的结果报告警告。
  • full：启用检查器，把项目中的所有函数都视为已标记，并对被忽略的结果报告警告。

警告管理

-nowarn

在编译期间抑制所有警告。

-Werror

把所有警告视为编译错误。

-Wextra

启用额外的声明、表达式和类型编译器检查，它们在成立时发出警告。

-Xrender-internal-diagnostic-names

实验性 - 通用

在警告旁打印内部诊断名称。这对于识别为 -Xwarning-level 选项配置的 DIAGNOSTIC_NAME 很有用。

-Xwarning-level

实验性 - 通用

配置特定编译器警告的严重级别：

1

kotlinc -Xwarning-level=DIAGNOSTIC_NAME:(error|warning|disabled)
  • error：只把指定的警告提升为错误。
  • warning：为指定的诊断发出警告，默认启用。
  • disabled：在整个模块中只抑制指定的警告。

你可以通过把模块级规则与特定规则结合来调整项目中的警告报告：

| 命令 | 说明 |

| -nowarn -Xwarning-level=DIAGNOSTIC_NAME:warning | 抑制除指定警告之外的所有警告。 | | -Werror -Xwarning-level=DIAGNOSTIC_NAME:warning | 把除指定警告之外的所有警告提升为错误。 | | -Wextra -Xwarning-level=DIAGNOSTIC_NAME:disabled | 启用除指定检查之外的所有额外检查。 |

如果你有许多想从通用规则中排除的警告，可以通过 @argfile 把它们列在单独的文件中。

你可以使用 -Xrender-internal-diagnostic-names 来发现 DIAGNOSTIC_NAME。

@argfile

从给定文件中读取编译器选项。这类文件可以包含带取值的编译器选项以及源文件的路径。选项和路径应以空白分隔。例如：

-include-runtime -d hello.jar hello.kt

要传入包含空白的值，请用单引号（’）或双引号（"）把它们括起来。如果值本身包含引号，请用反斜杠（\）转义。

-include-runtime -d 'My folder'

你也可以传入多个参数文件，例如把编译器选项与源文件分开。

1

$ kotlinc @compiler.options @classes

如果这些文件所在位置与当前目录不同，请使用相对路径。

1

$ kotlinc @options/compiler.options hello.kt

Kotlin/JVM 编译器选项

用于 JVM 的 Kotlin 编译器把 Kotlin 源文件编译为 Java 类文件。用于 Kotlin 到 JVM 编译的命令行工具是 kotlinc 和 kotlinc-jvm。你也可以用它们执行 Kotlin 脚本文件。

除了通用选项之外，Kotlin/JVM 编译器还有以下列出的选项。

-classpath path (-cp path)

在指定路径中搜索类文件。用系统路径分隔符（Windows 上是 ;，macOS/Linux 上是 :）分隔类路径中的各个元素。类路径可以包含文件和目录路径、ZIP 或 JAR 文件。

-d path

把生成的类文件放到指定位置。该位置可以是目录、ZIP 或 JAR 文件。

-include-runtime

把 Kotlin 运行时包含到生成的 JAR 文件中。这使生成的归档文件可以在任何支持 Java 的环境中运行。

-jdk-home path

如果自定义 JDK 主目录与默认的 JAVA_HOME 不同，请使用指定的 JDK 主目录并将其包含到类路径中。

-Xjdk-release=version

实验性 - 通用

指定生成的 JVM 字节码的目标版本。把类路径中 JDK 的 API 限制为指定的 Java 版本。会自动设置 -jvm-target version。可能的值为 1.8、9、10、…、26。

注意： 该选项并不保证对每个 JDK 发行版都有效。

-jvm-default mode

控制接口中声明的函数在 JVM 上如何编译为默认方法。

| 模式 | 说明 |

| enable | 在接口中生成默认实现，并在子类和 DefaultImpls 类中包含桥接函数。（默认） | | no-compatibility | 只在接口中生成默认实现，跳过兼容性桥接和 DefaultImpls 类。 | | disable | 只生成兼容性桥接和 DefaultImpls 类，跳过默认方法。 |

-jvm-target version

指定生成的 JVM 字节码的目标版本。可能的值为 1.8、9、10、…、26。默认值是 1.8。

-java-parameters

为方法参数生成用于 Java 1.8 反射的元数据。

-module-name name (JVM)

为生成的 .kotlin_module 文件设置自定义名称。

-no-jdk

不自动把 Java 运行时包含到类路径中。

-no-reflect

不自动把 Kotlin 反射（kotlin-reflect.jar）包含到类路径中。

-no-stdlib (JVM)

不自动把 Kotlin/JVM 标准库（kotlin-stdlib.jar）和 Kotlin 反射（kotlin-reflect.jar）包含到类路径中。

-script-templates classnames[,]

脚本定义模板类。请使用全限定类名，并用逗号（,）分隔。

-Xdump-directory

实验性 - 通用

为 -Xphases-to-dump-before 编译器选项配置转储文件目录。

-Xjvm-expose-boxed

实验性 - 通用

为模块中所有内联值类生成装箱版本，并为使用它们的函数生成装箱变体，使两者都可从 Java 访问。更多信息请参见从 Java 调用 Kotlin 指南中的内联值类。

-Xnullability-annotations

实验性 - 通用

配置 Kotlin 编译器如何解释来自特定 Java 包的可空性注解。

受支持注解和配置选项的完整列表请参见可空性注解。

Kotlin/JS 编译器选项

用于 JS 的 Kotlin 编译器把 Kotlin 源文件编译为 JavaScript 代码。用于 Kotlin 到 JS 编译的命令行工具是 kotlinc-js。

除了通用选项之外，Kotlin/JS 编译器还有以下列出的选项。

-libraries path

带 .meta.js 和 .kjsm 文件的 Kotlin 库的路径，用系统路径分隔符分隔。

-main {call|noCall}

定义执行时是否应调用 main 函数。

-meta-info

生成带元数据的 .meta.js 和 .kjsm 文件。在创建 JS 库时使用该选项。

-module-kind

编译器生成的 JS 模块类型：

要了解更多关于不同 JS 模块类型及其区别的信息，请参见这篇文章。

-no-stdlib (JS)

不自动把默认的 Kotlin/JS 标准库包含到编译依赖中。

-output filepath

设置编译结果的目标文件。该值必须是包含文件名的 .js 文件路径。

-output-postfix filepath

把指定文件的内容追加到输出文件的末尾。

-output-prefix filepath

把指定文件的内容添加到输出文件的开头。

-source-map

生成源映射。

-source-map-base-dirs path

把指定路径用作基础目录。基础目录用于计算源映射中的相对路径。

-source-map-embed-sources {always|never|inlining}

把源文件嵌入到源映射中。

-source-map-names-policy {simple-names|fully-qualified-names|no}

把你用 Kotlin 代码声明的变量名和函数名添加到源映射中。

| 设置 | 说明 | 示例输出 |

| simple-names | 添加变量名和简单函数名。（默认） | main | | fully-qualified-names | 添加变量名和完全限定函数名。 | com.example.kjs.playground.main | | no | 不添加任何变量名或函数名。 | 不适用 |

-source-map-prefix

为源映射中的路径添加指定前缀。

-target

为指定的 ECMA 版本生成 JS 文件。

-Xenable-implementing-interfaces-from-typescript

实验性 - 通用

允许从 JavaScript/TypeScript 实现用 @JsExport 注解导出的 Kotlin 接口。

-Xes-long-as-bigint

实验性 - 通用

在编译到现代 JavaScript（ES2020）时，支持用 JavaScript BigInt 类型表示 Kotlin Long 值。

-Xsuspend-lambda-exporting

实验性 - 通用

允许把 @JsExport 声明中声明的挂起 lambda 表达式导出为 JavaScript async 函数。

Kotlin/Native 编译器选项

Kotlin/Native 编译器把 Kotlin 源文件编译为面向受支持平台的原生二进制文件。用于 Kotlin/Native 编译的命令行工具是 kotlinc-native。

除了通用选项之外，Kotlin/Native 编译器还有以下列出的选项。

-enable-assertions (-ea)

在生成的代码中启用运行时断言。

-entry name (-e name)

指定限定的入口点名称。

-g

启用调试信息的生成。该选项会降低优化级别，不应与 -opt 选项一起使用。

-generate-test-runner (-tr)

生成用于从项目运行单元测试的应用程序。

-generate-no-exit-test-runner (-trn)

生成用于运行单元测试、且不会显式退出进程的应用程序。

-include-binary path (-ib path)

把外部二进制文件打包进生成的 klib 文件中。

-library path (-l path)

与该库链接。要了解在 Kotlin/Native 项目中使用库的方式，请参见 Kotlin/Native 库。

-library-version version (-lv version)

设置库版本。

-linker-option

在构建二进制文件期间向链接器传递一个参数。这可以用来链接某个原生库。

-linker-options args

在构建二进制文件期间向链接器传递多个参数。用空白分隔各个参数。

-list-targets

列出可用的硬件目标。

-manifest path

提供一个 manifest addend 文件。

-module-name name (Native)

为编译模块指定名称。该选项也可用于为导出到 Objective-C 的声明指定名称前缀：如何为我的 Kotlin 框架指定自定义 Objective-C 前缀/名称？

-native-library path (-nl path)

包含原生 bitcode 库。

-no-default-libs

禁止把用户代码与编译器附带的预构建平台库链接。

-nomain

假定 main 入口点由外部库提供。

-nopack

不要把库打包进 klib 文件。

-nostdlib

不与标准库链接。

-opt

启用编译优化，并生成运行时性能更好的二进制文件。不建议与 -g 选项一起使用，因为后者会降低优化级别。

-output name (-o name)

设置输出文件的名称。

-produce output (-p output)

指定输出文件类型：

  • program
  • static
  • dynamic
  • framework
  • library
  • bitcode

-repo path (-r path)

库搜索路径。更多信息请参见库搜索顺序。

-target target

设置硬件目标。要查看可用目标列表，请使用 -list-targets 选项。

-Xccall-mode

实验性 - 通用

为通过 cinterop 导入的 C 或 Objective-C 库启用新的互操作模式。

-Xoverride-konan-properties=min.version.*

实验性 - 通用

配置比 Kotlin 默认值更低的受支持 Apple 目标版本。例如：

1
2
3
4

kotlinc -Xoverride-konan-properties=minVersion.ios=14.0
kotlinc -Xoverride-konan-properties=minVersion.macos=11.0
kotlinc -Xoverride-konan-properties=minVersion.tvos=14.0
kotlinc -Xoverride-konan-properties=minVersion.watchos=7.0
最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)