Kotlin/Native 二进制文件选项

本章列出了实用的 Kotlin/Native 二进制文件选项, 可以用来配置 Kotlin/Native 最终二进制文件, 还介绍了在项目中设置二进制文件选项的方法.

如何启用

你可以在 gradle.properties 文件或构建文件中, 启用二进制文件选项, 也可以将这些选项传递为编译器参数.

在 Gradle 属性文件中

你可以在项目的 gradle.properties 文件中, 使用 kotlin.native.binary 属性设置二进制文件选项. 例如:

kotlin.native.binary.latin1Strings=true

在构建文件中

你可以在 build.gradle.kts 文件中, 为项目设置二进制文件选项:

使用 binaryOption 属性, 针对特定二进制文件进行设置. 例如:
kotlin { iosArm64 { binaries { framework { binaryOption("smallBinary", "true") } } } }
在 freeCompilerArgs 属性中, 通过 -Xbinary=$option=$value 编译器选项设置. 例如:
kotlin { iosArm64 { compilations.configureEach { compilerOptions.configure { freeCompilerArgs.add("-Xbinary=smallBinary=true") } } } }

在命令行编译器中

你可以在执行 Kotlin/Native 编译器时, 在命令行中, 以 -Xbinary=$option=$value 的形式, 直接传递二进制文件选项. 例如:

kotlinc-native main.kt -Xbinary=enableSafepointSignposts=true

二进制文件选项

选项	值	说明	状态
`enableReleaseBinaryCache`	`true` `false` (默认值)	允许编译器在发布模式中使用缓存, 能够加快构建速度, 但会损失一部分编译器优化.	从 2.4.20 开始, 为实验性功能
`objcExportBlockExplicitParameterNames`	`true` `false (默认值)`	为导出的 Objective-C 头文件中的函数类型, 添加明确的参数名称.	从 2.2.20 开始, 为实验性功能
`smallBinary`	`true` `false` (默认值)	减小发布版本二进制文件的大小.	从 2.2.20 开始, 为实验性功能
`stackProtector`	`yes` `strong` `all` `no` (默认值)	启用栈金丝雀(Stack Canary): 对易受攻击的函数使用 `yes`, 对所有函数使用 `all`, 使用 `strong` 采用更强的启发式算法.	从 2.2.20 开始可用
`pagedAllocator`	`true` (默认值) `false`	控制分配(缓冲)的分页. 当值为 `false` 时, 内存分配器按对象为单位预留内存.	从 2.2.0 开始, 为实验性功能
`latin1Strings`	`true` `false` (默认值)	控制对 Latin-1 编码字符串的支持, 以减小应用程序二进制文件大小, 并调整内存消耗.	从 2.2.0 开始, 为实验性功能
`mmapTag`	`UInt`	控制内存标记, 在 Apple 平台上跟踪内存消耗需要这个功能. 可用值为 `240`-`255` (默认值为 `246`); `0` 禁用内存标记.	从 2.2.0 开始可用
`disableMmap`	`true` `false` (默认值)	控制默认的内存分配器. 当值为 `true` 时, 使用 `malloc` 内存分配器, 而不是 `mmap`.	从 2.2.0 开始可用
`gc`	`cms` (默认值) `pmcs` `stwms` `noop`	控制垃圾收集行为: `cms` 使用并发的标记和清除 `pmcs` 使用并行的标记和并发的清除 `stwms` 使用简单的完全停顿标记和清除 `noop` 禁用垃圾收集	从 2.4.0 开始, 默认值为 `cms`
`gcMarkSingleThreaded`	`true` `false` (默认值)	禁用垃圾收集中标记阶段的并行化. 在大尺寸的堆上, 可能会增加 GC 暂停时间.	从 1.7.20 开始可用
`enableSafepointSignposts`	`true` `false` (默认值)	启用对项目中 GC 相关暂停的跟踪, 用于在 Xcode Instruments 中调试.	从 2.0.20 开始可用
`preCodegenInlineThreshold`	`UInt`	在 Kotlin IR 编译器中配置内联优化过程, 这个过程在实际代码生成阶段之前执行(默认为禁用). 推荐的 token 数量(编译器解析的代码单元)为 40.	从 2.1.20 开始, 为实验性功能
`objcDisposeOnMain`	`true` (默认值) `false`	控制 Swift/Objective-C 对象的反初始化. 当值为 `false` 时, 反初始化在特殊的 GC 线程上进行, 而不是在主线程上.	从 1.9.0 开始可用
`appStateTracking`	`enabled` `disabled` (默认值)	控制应用程序在后台运行时, 基于定时器的垃圾收集器调用. 当值为 `enabled` 时, 仅在内存消耗过高时才会调用 GC.	从 1.7.20 开始, 为实验性功能
`bundleId`	`String`	在 `Info.plst` 文件中设置 Bundle ID (`CFBundleIdentifier`).	从 1.7.20 开始可用
`bundleShortVersionString`	`String`	在 `Info.plst` 文件中设置 Bundle 的短版本号 (`CFBundleShortVersionString`).	从 1.7.20 开始可用
`bundleVersion`	`String`	在 `Info.plst` 文件中设置 Bundle 的版本号 (`CFBundleVersion`).	从 1.7.20 开始可用
`sourceInfoType`	`libbacktrace` `coresymbolication` (Apple 目标平台) `noop` (默认值)	向异常的堆栈跟踪(Stack Trace)添加文件位置和行号信息. `coresymbolication` 只能用于 Apple 目标平台, 并且在调试模式下, 对 macOS 和 Apple 模拟器默认启用.	从 1.6.20 开始, 为实验性功能

下一步做什么?

了解如何构建最终的原生二进制文件.

2026/09/29