Kotlin 编译器选项

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

这些编译器被用于：

IDE，当您为 Kotlin 项目点击构建或运行按钮时。
Gradle，当您在控制台或 IDE 中调用 gradle build 时。
Maven，当您在控制台或 IDE 中调用 mvn compile 或 mvn test-compile 时。

您也可以按照使用命令行编译器教程中的说明，手动运行 Kotlin 编译器。

编译器选项

Kotlin 编译器具有许多用于定制编译过程的选项。本页列出了针对不同目标的编译器选项以及每个选项的说明。

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

在 IntelliJ IDEA 中，在 Settings/Preferences | Build, Execution, Deployment | Compiler | Kotlin Compiler 的 Additional command line parameters 文本框中输入编译器实参。
如果您使用 Gradle，请在 Kotlin 编译任务的 compilerOptions 属性中指定编译器实参。有关详细信息，请参阅 Gradle 编译器选项。
如果您使用 Maven，请在 Maven 插件节点的 <configuration> 元素中指定编译器实参。有关详细信息，请参阅 Maven。
如果运行命令行编译器，请直接在实用工具调用中添加编译器实参，或将其写入实参文件 (argfile)。
例如：
bash
```
$ kotlinc hello.kt -include-runtime -d hello.jar
```
在 Windows 上，当您传递包含分隔符（空格、=、;、,）的编译器实参时，请用双引号 (") 包围这些实参。
```
$ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"
```

编译器选项架构

所有编译器选项的通用架构以 JAR 构件的形式发布在 org.jetbrains.kotlin:kotlin-compiler-arguments-description 下。该构件包括所有编译器选项说明的代码表示形式和 JSON 等效形式（供非 Kotlin 使用者使用）。此外还包含元数据，例如每个选项引入或稳定的版本。

通用选项

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

-version

显示编译器版本。

-verbose

启用详细日志输出，其中包括编译过程的详细信息。

-script

运行 Kotlin 脚本文件。使用此选项调用时，编译器将执行给定实参中的第一个 Kotlin 脚本 (*.kts) 文件。

-help (-h)

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

Experimental

-X

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

-kotlin-home 路径

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

-P plugin:pluginId:optionName=value

向 Kotlin 编译器插件传递选项。核心插件及其选项列在文档的核心编译器插件部分。

-language-version 版本

此选项根据指定的语言版本设置支持的语法和语义。例如，使用 Kotlin 编译器版本 2.2.0 并配合 -language-version=1.9，可以让您仅使用 1.9 或更早版本的语言功能和标准库 API。这有助于逐步迁移到较新的 Kotlin 版本。

-api-version 版本

仅允许使用来自指定版本的 Kotlin 捆绑库的声明。

-progressive

为编译器启用渐进模式。

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

@argfile

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

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

要传递包含空格的值，请用单引号 (') 或双引号 (") 包围它们。如果值中包含引号，请使用反斜杠 (\) 对其进行转义。

-include-runtime -d 'My folder'

您还可以传递多个实参文件，例如，将编译器选项与源文件分开。

bash

$ kotlinc @compiler.options @classes

如果文件位于与当前目录不同的位置，请使用相对路径。

bash

$ kotlinc @options/compiler.options hello.kt

-opt-in 注解

通过给定完全限定名称的需求注解，启用需要选择性加入 (opt-in) 的 API 的使用。

Experimental

-Xrepl

激活 Kotlin REPL。

bash

kotlinc -Xrepl

Experimental

-Xannotation-target-all

启用实验性的注解 all 使用处目标：

bash

kotlinc -Xannotation-target-all

Experimental

-Xannotation-default-target=param-property

启用新的实验性注解使用处目标默认规则：

bash

kotlinc -Xannotation-default-target=param-property

警告管理

-nowarn

在编译期间禁止显示所有警告。

-Werror

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

-Wextra

启用额外的编译器声明、表达式和类型检查，如果检查结果为 true，则发出警告。

Experimental

-Xrender-internal-diagnostic-names

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

Experimental

-Xwarning-level

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

bash

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。

Experimental

-Xdata-flow-based-exhaustiveness

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

Experimental

-Xallow-reified-type-in-catch

在 inline 函数的 catch 子句中启用对具体化 (reified) Throwable 类型实参的支持。

Experimental

Kotlin 契约选项

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

-Xallow-contracts-on-more-functions

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

-Xallow-condition-implies-returns-contracts

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

-Xallow-holdsin-contract

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

Experimental

-Xreturn-value-checker

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

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

-Xcompiler-plugin-order=

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

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

bash

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

这将导致以下运行顺序：

plugin.first
plugin.middle
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 with receiver	`org.jetbrains.kotlin.samWithReceiver`
Serialization	`org.jetbrains.kotlinx.serialization`

此运行顺序仅控制编译器插件的后端，不控制前端。

Experimental

-Xphases-to-dump-before

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

Experimental

-Xname-based-destructuring

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

该选项支持以下模式：

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

Kotlin/JVM 编译器选项

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

除了通用选项外，Kotlin/JVM 编译器还具有下列选项。

-classpath 路径 (-cp 路径)

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

-d 路径

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

-include-runtime

将 Kotlin 运行时包含在生成的 JAR 文件中。使生成的归档文件可在任何启用 Java 的环境中运行。

-jdk-home 路径

如果要包含在类路径中的自定义 JDK 根目录与默认的 JAVA_HOME 不同，请使用此选项。

Experimental

-Xjdk-release=version

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

此选项不保证对每个 JDK 发行版都有效。

-jvm-target 版本

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

-java-parameters

为方法形参上的 Java 1.8 反射生成元数据。

-module-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 类名[,]

脚本定义模板类。使用完全限定类名并以逗号 (,) 分隔。

Experimental

-Xjvm-expose-boxed

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

-jvm-default 模式

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

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

Experimental

-Xdump-directory

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

Experimental

-Xnullability-annotations

配置 Kotlin 编译器如何解释来自特定 Java 软件包的为 null 性注解。

有关受支持注解和配置选项的完整列表，请参阅为 null 性注解。

Kotlin/JS 编译器选项

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

除了通用选项外，Kotlin/JS 编译器还具有下列选项。

-target

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

-libraries 路径

包含 .meta.js 和 .kjsm 文件的 Kotlin 库路径，由系统路径分隔符分隔。

-main {call|noCall}

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

-meta-info

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

-module-kind

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

umd - 一个 Universal Module Definition 模块
commonjs - 一个 CommonJS 模块
amd - 一个 Asynchronous Module Definition 模块
plain - 一个普通的 JS 模块

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

-no-stdlib (JS)

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

-output 文件路径

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

-output-postfix 文件路径

将指定文件的内容添加到输出文件的末尾。

-output-prefix 文件路径

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

-source-map

生成源代码映射。

-source-map-base-dirs 路径

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

-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`	不添加变量或函数名称。	N/A

-source-map-prefix

向源代码映射中的路径添加指定的前缀。

Experimental

-Xes-long-as-bigint

在编译为现代 JavaScript (ES2020) 时，启用对 JavaScript BigInt 类型的支持以表示 Kotlin Long 值。

Experimental

-Xenable-implementing-interfaces-from-typescript

允许从 JavaScript/TypeScript 中实现 Kotlin 接口，这些接口需使用 @JsExport 注解导出。

Kotlin/Native 编译器选项

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

除了通用选项外，Kotlin/Native 编译器还具有下列选项。

-enable-assertions (-ea)

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

-g

启用发射调试信息。此选项会降低优化级别，不应与 -opt 选项结合使用。

-generate-test-runner (-tr)

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

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

生成一个用于在没有显式进程退出的情况下运行单元测试的应用程序。

-include-binary 路径 (-ib 路径)

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

-library 路径 (-l 路径)

与库链接。要了解在 Kotlin/native 项目中使用库的信息，请参阅 Kotlin/Native 库。

-library-version 版本 (-lv 版本)

设置库版本。

-list-targets

列出可用的硬件目标。

-manifest 路径

提供一个清单附加文件。

-module-name 名称 (Native)

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

-native-library 路径 (-nl 路径)

包含原生 bitcode 库。

-no-default-libs

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

-nomain

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

-nopack

不将库打包到 klib 文件中。

-linker-option

在构建二进制文件期间向链接器传递一个实参。这可用于与某些原生库链接。

-linker-options 实参

在构建二进制文件期间向链接器传递多个实参。实参之间以空格分隔。

-nostdlib

不与标准库链接。

-opt

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

-output 名称 (-o 名称)

设置输出文件的名称。

-entry 名称 (-e 名称)

指定限定的入口点名称。

-produce 输出 (-p 输出)

指定输出文件种类：

program
static
dynamic
framework
library
bitcode

-repo 路径 (-r 路径)

库搜索路径。有关更多信息，请参阅库搜索序列。

-target 目标

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

Experimental

-Xccall-mode

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

运行 Dokka

输出格式

检索

操作与操作符

Kotlin 编译器选项 ​

编译器选项 ​

编译器选项架构 ​

通用选项 ​

-version ​

-verbose ​

-script ​

-help (-h) ​

-X

-kotlin-home 路径 ​

-P plugin:pluginId:optionName=value ​

-language-version 版本 ​

-api-version 版本 ​

-progressive ​

@argfile ​

-opt-in 注解 ​

-Xrepl

-Xannotation-target-all

-Xannotation-default-target=param-property

警告管理 ​

-nowarn ​

-Werror ​

-Wextra ​

-Xrender-internal-diagnostic-names

-Xwarning-level

-Xdata-flow-based-exhaustiveness

-Xallow-reified-type-in-catch

Kotlin 契约选项

-Xallow-contracts-on-more-functions ​

-Xallow-condition-implies-returns-contracts ​

-Xallow-holdsin-contract ​

-Xreturn-value-checker

-Xcompiler-plugin-order= ​

-Xphases-to-dump-before

-Xname-based-destructuring

Kotlin/JVM 编译器选项 ​

-classpath 路径 (-cp 路径) ​

-d 路径 ​

-include-runtime ​

-jdk-home 路径 ​

-Xjdk-release=version

-jvm-target 版本 ​

-java-parameters ​

-module-name 名称 (JVM) ​

-no-jdk ​

-no-reflect ​

-no-stdlib (JVM) ​

-script-templates 类名[,] ​

-Xjvm-expose-boxed

-jvm-default 模式 ​

-Xdump-directory

-Xnullability-annotations

Kotlin/JS 编译器选项 ​

-target ​

-libraries 路径 ​

-main {call|noCall} ​

-meta-info ​

-module-kind ​

-no-stdlib (JS) ​

-output 文件路径 ​

-output-postfix 文件路径 ​

-output-prefix 文件路径 ​

-source-map ​

-source-map-base-dirs 路径 ​

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

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

-source-map-prefix ​

-Xes-long-as-bigint

-Xenable-implementing-interfaces-from-typescript

Kotlin/Native 编译器选项 ​

-enable-assertions (-ea) ​

-g ​

-generate-test-runner (-tr) ​

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

-include-binary 路径 (-ib 路径) ​

-library 路径 (-l 路径) ​

Kotlin 编译器选项

编译器选项

编译器选项架构

通用选项

-version

-verbose

-script

-help (-h)

-kotlin-home 路径

-P plugin:pluginId:optionName=value

-language-version 版本

-api-version 版本

-progressive

@argfile

-opt-in 注解

警告管理

-nowarn

-Werror

-Wextra

-Xallow-contracts-on-more-functions

-Xallow-condition-implies-returns-contracts

-Xallow-holdsin-contract

-Xcompiler-plugin-order=

Kotlin/JVM 编译器选项

-classpath 路径 (-cp 路径)

-d 路径

-include-runtime

-jdk-home 路径

-jvm-target 版本

-java-parameters

-module-name 名称 (JVM)

-no-jdk

-no-reflect

-no-stdlib (JVM)

-script-templates 类名[,]

-jvm-default 模式

Kotlin/JS 编译器选项

-target

-libraries 路径

-main {call|noCall}

-meta-info

-module-kind

-no-stdlib (JS)

-output 文件路径

-output-postfix 文件路径

-output-prefix 文件路径

-source-map

-source-map-base-dirs 路径

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

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

-source-map-prefix

Kotlin/Native 编译器选项

-enable-assertions (-ea)

-g

-generate-test-runner (-tr)

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

-include-binary 路径 (-ib 路径)

-library 路径 (-l 路径)