Kotlin 编译器选项

Kotlin 的各个发布版都带有针对各种编译目标的编译器: JVM, JavaScript, 以及所支持的各种平台的原生二进制可执行文件(native binary).

这些编译器会在以下情况下使用:

当你对你的 Kotlin 工程按下 Compile 或 Run 按钮时, 由 IDE 使用.
当你在控制台或在 IDE 内调用 gradle build 命令时, 由 Gradle 使用.
当你在控制台或在 IDE 内调用 mvn compile 或 mvn test-compile, 由 Maven 使用.

你也可以从命令行手动运行 Kotlin 编译器, 详情请参见教程使用命令行编译器.

编译器选项

Kotlin 编译器带有很多选项, 用于控制编译过程. 本章会列出针对各种编译目标的编译器选项, 并分别进行介绍.

有几种方式来设置各个编译器选项, 以及相应的值(即编译参数(compiler argument)):

在 IntelliJ IDEA 中, 可以在 Settings/Preferences | Build, Execution, Deployment | Compiler | Kotlin Compiler 设定窗口的 Additional command line parameters 文本框中输入编译器参数
如果使用 Gradle, 可以在 Kotlin 编译任务的 compilerOptions 属性中指定编译参数. 详情请参见 Gradle 编译器选项.
如果使用 Maven, 可以在 Maven 插件的 <configuration> 元素中指定编译参数 . 详情请参见 Maven.
如果在命令行运行编译器, 可以在调用编译器时直接添加编译参数, 或者将编译参数写在参数文件内.
例如:
$ kotlinc hello.kt -include-runtime -d hello.jar
在 Windows 上, 如果传递的编译器参数中包含分隔字符(空格, =, ;, ,), 请将这些参数值使用双引号(" )括起.
$ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"

各平台共通选项

下面是所有 Kotlin 编译器的共通选项.

-version

显示编译器版本.

-verbose

允许输出最详细的 log, 其中包括编译过程的各种细节信息.

-script

运行 Kotlin 脚本文件. 使用这个选项调用编译器时, 编译器会运行参数中指定的第一个 Kotlin 脚本文件(*.kts).

-help (-h)

显示编译器使用方法的帮助信息, 然后退出. 帮助信息中只会显示标准的编译选项. 如果需要显示更多的高级编译选项, 请使用 -X 参数.

-X

显示编译器高级选项的帮助信息, 然后退出. 这些选项目前还不稳定: 选项的名称和行为都有可能变更, 并且不会有相关公告.

-kotlin-home path

对 Kotlin 编译器指定一个自定义的路径, 用来查找运行时期的库文件.

-P plugin:pluginId:optionName=value

向 Kotlin 编译器插件传递一个选项. 核心编译器插件, 以及它们的选项, 请参见本文档的核心编译器插件章节.

-language-version version

与指定的 Kotlin 版本保持源代码级兼容.

-api-version version

允许使用从指定的 Kotlin 版本的库才开始提供的 API 声明.

-progressive

允许编译器使用渐进模式(progressive mode).

在渐进模式下, 对不稳定代码中功能废弃和 bug 修正, 会立即生效, 而不会等待完整的版本迁移周期完成. 渐进模式下编写的代码可以向后兼容(backwards compatible); 但是, 非渐进模式下编写的代码, 在渐进模式下编译时, 可能导致编译错误.

@argfile

从指定的文件中读取编译器选项. 这样的文件可以包含编译器选项, 相应的值, 以及源代码文件的路径. 选项和文件路径使用空格分隔. 比如:

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

如果想要传递的参数值本身包含空格, 请使用单引号 (') 或双引号 (") 将参数值括起. 如果参数值本身包含引号, 请使用反斜线 (\) 转义符表示.

-include-runtime -d 'My folder'

也可以传递多个参数文件, 比如, 如果想要将编译器选项和源代码文件分开的情况.

$ kotlinc @compiler.options @classes

如果文件位置不在当前目录下, 请使用相对路径.

$ kotlinc @options/compiler.options hello.kt

-opt-in annotation

指定注解的全限定名称, 通过这个注解启用明确要求使用者同意(opt-in) API.

-Xrepl

启动 Kotlin REPL.

kotlinc -Xrepl

-Xannotation-target-all

启用实验性功能注释的 all 使用目标(Use-site Target):

kotlinc -Xannotation-target-all

-Xannotation-default-target=param-property

启用新的实验性功能注释使用目标(Use-site Target)的默认规则:

kotlinc -Xannotation-default-target=param-property

警告管理

-nowarn

在编译过程中禁止所有的警告信息.

-Werror

将所有的警告作为编译错误处理.

-Wextra

启用声明, 表达式, 和类型的额外编译器检查, 如果检查结果为 true, 会产生警告.

-Xwarning-level

对特定的编译器警告配置严重性级别:

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, 在单独的文件中列出这些警告.

Kotlin/JVM 编译器选项

针对 JVM 平台的 Kotlin 编译器将 Kotlin 源代码文件编译为 Java class 文件. 将 Kotlin 文件编译到 JVM 平台的命令行工具是 kotlinc 和 kotlinc-jvm. 也可以使用它们来运行 Kotlin 脚本文件.

除共通选项之外, Kotlin/JVM 编译器还支持以下选项.

-classpath path (-cp path)

在指定的路径中查找 class 文件. 如果 classpath 中存在多个路径, 请使用操作系统的路径分隔符来分隔(对 Windows 系统是 ;, 对 macOS/Linux 系统是 :). classpath 可以包含文件路径, 目录路径, ZIP 文件, 或 JAR 文件.

-d path

将生成的 class 文件输出到指定的位置. 输出位置可以是一个目录, 一个 ZIP 文件, 或一个 JAR 文件.

-include-runtime

将 Kotlin 运行时库文件包含在最终输出的结果 JAR 文件中. 这样将使得最终输出的包可以在任何安装了 Java 环境中运行.

-jdk-home path

如果自定义的 JDK home 目录与默认的 JAVA_HOME 不用, 这个选项会将它添加到 classpath 中.

-Xjdk-release=version

指定生成的 JVM 字节码的目标版本. 将类路径中的 JDK API 限制为指定的 Java 版本. 自动设置 -jvm-target version. 可以指定的值是 1.8, 9, 10, ..., 24.

-jvm-target version

指定编译产生的 JVM 字节码(bytecode)版本. 可以指定的值是 1.8, 9, 10, ..., 24. 默认值是 1.8.

-java-parameters

针对 Java 1.8 的方法参数反射(reflection on method parameter)生成元信息(metadata). 译者注: 等于 Java 1.8 编译参数 -parameters, 参见 javac 命令行编译器

-module-name name (JVM)

对编译产生的 .kotlin_module 指定一个自定义的名称.

-no-jdk (JVM)

不要自动将 Java 运行时期库文件添加到 classpath 中.

-no-reflect

不要自动将 Kotlin 反射库文件(kotlin-reflect.jar) 添加到 classpath 中.

-no-stdlib

不要自动将 Kotlin/JVM 标准库文件(kotlin-stdlib.jar) 和 Kotlin 反射库文件(kotlin-reflect.jar) 添加到 classpath 中.

-script-templates classnames[,]

脚本定义的模板类. 请使用类的完全限定名称, 如果有多个, 请使用逗号(,) 分隔.

-Xjvm-expose-boxed

对模块中的所有的内联值类(Inline Value Class)生成装箱版本(Boxed), 并对使用它们的函数生成装箱的变体, 以供 Java 访问. 详情请参见在 Java 中调用 Kotlin 代码指南: 内联值类(Inline Value Class) 小节.

-jvm-default mode

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

模式	说明
`enable`	生成接口中的默认实现, 并包含子类中的桥接函数(Bridge Function)和 `DefaultImpls` 类. (默认值)
`no-compatibility`	只生成接口中的默认实现, 略过兼容性桥接函数和 `DefaultImpls` 类.
`disable`	只生成兼容性桥接函数和 `DefaultImpls` 类, 略过默认方法.

Kotlin/JS 编译器选项

针对 JS 平台的 Kotlin 编译器将 Kotlin 源代码文件编译为 JavaScript 代码. 将 Kotlin 文件编译到 JS 平台的命令行工具是 kotlinc-js.

除共通选项之外, Kotlin/JS 编译器还支持以下选项.

-target {es5|es2015}

针对指定的 ECMA 版本生成 JS 文件.

-libraries path

包含 .meta.js 和 .kjsm 文件的 Kotlin 库路径, 如果有多个路径, 请使用操作系统的路径分隔符分隔.

-main {call|noCall}

指定执行时是否要调用 main 函数.

-meta-info

生成 .meta.js 和 .kjsm 文件时附带元信息(metadata). 开发 JS 库时, 请使用这个选项 .

-module-kind {umd|commonjs|amd|plain}

指定编译器生成的 JS 模块类型:

umd - 统一模块定义(Universal Module Definition) 模块
commonjs - CommonJS 模块
amd - 异步模块定义(Asynchronous Module Definition) 模块
plain - 普通 JS 模块

关于各种 JS 模块类型, 以及它们之间的差别, 请参见这篇文章.

-no-stdlib (JS)

不要自动将默认的 Kotlin/JS 标准库添加到编译依赖中.

-output filepath

指定编译结果的输出目标文件. 参数值必须是一个 .js 文件路径, 包含文件名.

-output-postfix filepath

将指定文件的内容添加到编译输出文件的末尾部分.

-output-prefix filepath

将指定文件的内容添加到编译输出文件的先头部分.

-source-map

生成源代码映射文件(source map).

-source-map-base-dirs path

使用指定的路径作为起始目录(base directory). 起始目录用来计算源代码映射文件(source map)中的相对路径.

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

是否将源代码文件嵌入到源代码映射文件(source map)中.

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

将你在 Kotlin 代码中声明的变量和函数名称添加到源代码映射文件(source map)中.

设置	说明	输出示例
`simple-names`	添加变量名称和函数的简单名称. (默认值)	`main`
`fully-qualified-names`	添加变量名称和函数完全限定名称.	`com.example.kjs.playground.main`
`no`	不添加变量名称和函数名称.	无

-source-map-prefix

向源代码映射文件(source map)中的路径添加指定的前缀.

Kotlin/Native 编译器选项

Kotlin/Native 编译器将 Kotlin 源代码文件编译为所支持的各种平台的二进制可执行文件(native binary). Kotlin/Native 编译的命令行工具是 kotlinc-native.

除共通选项之外, Kotlin/Native 编译器还支持以下选项.

-enable-assertions (-ea)

在生成的代码中允许运行时断言(runtime assertion).

-g

允许编译产生 debug 信息. 这个选项会降低代码优化的级别, 并且不应该与 -opt 选项组合使用.

-generate-test-runner (-tr)

生成一个应用程序, 用于在工程中运行单元测试.

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

生成一个应用程序, 用于运行单元测试, 但不会有明确的进程结束信息(explicit process exit).

-include-binary path (-ib path)

将外部的二进制文件打包到编译产生的 klib 文件内.

-library path (-l path)

链接指定的库文件. 关于在 Kotlin/native 工程中如何使用库, 请参见 Kotlin/Native 库.

-library-version version (-lv version)

指定库的版本.

-list-targets

列出可用的硬件目标平台(hardware target).

-manifest path

指定一个 manifest 补充文件.

-module-name name (Native)

为编译产生的模块指定名称. 这个选项也可以用来对导出给 Objective-C 的声明指定名称前缀: 怎样为 Kotlin 框架指定自定义的 Objective-C 前缀?

-native-library path (-nl path)

包含原生的 bitcode 库文件.

-no-default-libs

不要将用户代码与编译器附带的预先构建的平台库文件链接.

-nomain

假定外部的库文件会提供应用程序启动时的 main 入口点(entry point).

-nopack

不要将库文件打包进入 klib 文件.

-linker-option

在二进制文件构建过程中, 向链接程序传递一个参数. 这个选项可以用来链接到某些原生库文件.

-linker-options args

在二进制文件构建过程中, 向链接程序传递多个参数. 参数之间用空格分隔.

-nostdlib

不要链接到标准库.

-opt

允许编译优化(compilation optimization), 产生运行期性能更好的二进制文件. 不推荐将与 -g 选项组合使用, -g 选项会降低优化级别.

-output name (-o name)

指定编译输出文件的名称.

-entry name (-e name)

指定入口点的限定名称(qualified entry point name).

-produce output (-p output)

指定编译输出文件的类型:

program
static
dynamic
framework
library
bitcode

-repo path (-r path)

库文件的搜索路径. 详情请参见, 库的查找顺序.

-target target

指定编译的硬件目标平台(hardware target). 要查看可选择的硬件目标平台, 请使用 -list-targets 选项.

2025/08/04