mcpField
K
kotlin-tooling-native-build-performance

kotlin-tooling-native-build-performance

github.com/kotlin开发1.1k976 次安装7 周前更新
代码仓库

关于 kotlin-tooling-native-build-performance

面向 Kotlin/Native 开发者的构建性能诊断技能，要求按相同命令和构建状态测量，再逐项实施安全优化，同时保持 CI 发布行为不变。

主要功能

  1. 01分类慢构建场景与耗时阶段
  2. 02运行只读静态审计脚本
  3. 03按相同构建状态测量前后耗时
  4. 04按安全顺序调整缓存与构建目标
  5. 05验证 CI 发布产物保持不变

适用场景

  1. 01定位本地 iOS 开发循环的耗时任务
  2. 02分析 CI 重复下载 Kotlin/Native 的原因
  3. 03减少不必要的目标或发布构建
  4. 04评估 Gradle 缓存与生成代码开销

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/kotlin/kotlin-agent-skills --skill kotlin-tooling-native-build-performance

安装后在 Claude Code 中输入/kotlin-tooling-native-build-performance确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
EVALUATION.md
references/
artifacts-and-targets.md
caching-and-gradle.md
experimental.md
exports-and-generated-code.md
scripts/
audit-native-build.sh

详细介绍

Kotlin/Native 构建性能

将“iOS 构建很慢”转化为可测量的诊断结果和一小组安全的修复方案。始终遵循两条规则：

  1. 绝不牺牲必需的发布行为。加快本地开发循环，不得改变 CI 发布的内容。
  2. 使用相同命令和相同构建状态测量修复前后的表现。未经测量的修复只是猜测。

步骤 0：判断耗时场景

修改任何内容之前，先确认四个事实：在哪里（本地还是 CI）、做什么（调试反馈循环还是发布／分发制品）、状态（首次构建、干净构建、热缓存还是无操作），以及阶段（日志中哪些任务耗时最多）。然后根据主要症状进行判断：

构建日志中的症状可能原因参阅
本地开发循环中出现 linkRelease* 或 *ReleaseXCFramework 任务为开发构建分发制品artifacts-and-targets
每次 CI 运行都会下载 Kotlin/Native 编译器发行版各次运行之间未保留 ~/.konancaching-and-gradle
首个任务启动前长时间停顿配置阶段未启用配置缓存caching-and-gradle
只需要一个模拟器，却构建了所有 iOS 目标使用了范围过广的任务（build、assemble、assemble*XCFramework）或存在未使用的目标artifacts-and-targets
ksp* 任务出现在 compileKotlinIos* 之前原生路径上存在代码生成工作exports-and-generated-code
少量源代码改动就会重新编译并重新链接所有内容编译器缓存已禁用，或缺少增量构建caching-and-gradle、experimental
多个 link* 任务同时运行时机器负载过高并行原生链接caching-and-gradle、工作线程数注意事项

步骤 1：审查并测量

  1. 在项目根目录运行静态审计：

    scripts/audit-native-build.sh /path/to/project

    此审计为只读操作，会输出 file:line 格式的发现（已禁用的缓存、范围过广的本地任务、transitiveExport、范围过广的 KSP 配置、缺失的 CI .konan 缓存），每项都会指向包含修复方案的参考文件。 这些发现只是线索，并非定论——请结合项目策略逐项确认。

  2. 找出用户实际等待的命令：脚本、CI 步骤，或 Xcode 构建阶段中的 Gradle 调用。优化该命令，而不是自行挑选的任务。

  3. 条件允许时，运行两次。首次构建会下载 Kotlin/Native 组件并填充缓存；只有第二次及之后的运行才具有代表性。先按任务分析耗时，再判断是否该归咎于编译器：

    kotlin.build.report.output=file   # writes build/reports/kotlin-build/

    Gradle 的 --scan 或 --profile 也可以使用。

  4. 如果无法运行构建（没有 macOS 主机或 Xcode），请改为分析日志、构建扫描或已提交到代码库的指标，并明确说明结论是基于静态分析得出的。

步骤 2：按安全顺序修复

每次只应用一项修复，并在过程中重新测量：

  1. 恢复健康的默认设置——移除缓存／守护进程变通方案，启用 Gradle 构建缓存和配置缓存，在 CI 中保持 ~/.konan 为热缓存，更新 Kotlin：references/caching-and-gradle.md
  2. 只构建反馈循环所需的内容——每个循环使用一个具体任务、选择正确的集成方式，并采用有充分理由的目标矩阵： references/artifacts-and-targets.md
  3. 降低导出和代码生成成本——移除 transitiveExport，缩小 export(...) 的范围，将 KSP 工作限定在需要它的原生编译上： references/exports-and-generated-code.md
  4. 最后再尝试实验性开关，并征得用户同意： references/experimental.md

示例

一位使用 Apple Silicon Mac 的开发者抱怨说：“每次修改共享模块都要花 12 分钟”。他们的构建循环运行 ./gradlew :shared:assembleXCFramework。 第二次（热）运行的构建扫描显示：

:shared:linkReleaseFrameworkIosArm64             348s
:shared:linkReleaseFrameworkIosX64               341s
:shared:compileKotlinIosX64                       96s
:shared:linkDebugFrameworkIosSimulatorArm64       41s
:shared:compileKotlinIosSimulatorArm64            38s
configuration phase                               64s

推理过程：

  • 构建循环是本地 + 调试 + 热构建，但约 690 秒花在了 linkRelease* 上—— Release 链接比 Debug 慢一个数量级，而且只有 CI 需要它。将本地命令替换为 :shared:linkDebugFrameworkIosSimulatorArm64（如果由 Xcode 驱动构建，则替换为 Xcode 嵌入任务）。(artifacts-and-targets)
  • 所有 iosX64 工作都用于 Intel 模拟器；移除该目标前，先确认团队是否仍支持它。(artifacts-and-targets)
  • 每次运行都要花费 64 秒进行配置；试用 org.gradle.configuration-cache=true 后，这部分耗时即可消除。(caching-and-gradle)
  • 修改后的预期构建循环：热构建时约 40 秒编译 + 约 40 秒链接—— 重新运行新命令两次并进行比较，以确认这一点。
  • CI 中的 assembleXCFramework 保持不变；请在报告中明确说明。

验证

  • 重新运行完全相同的基准命令；比较热构建与热构建，而不是热构建与冷构建。
  • 启用配置缓存后运行第二次，确认输出显示正在复用缓存。
  • 本地开发日志中不再包含 linkRelease*、 *ReleaseXCFramework 或已移除的代码生成任务。
  • CI 仍会生成所有必需的 Release 构建产物，且保持不变。
  • 测试通过，并且应用仍可从 Xcode 运行。
  • scripts/audit-native-build.sh 报告的所有发现都已经过慎重接受并记录。

报告你的更改

最后附上一段简短的性能说明：

  • 构建缓慢的场景（本地/CI、Debug/Release、冷/热）以及测量证据——或者说明分析是静态分析。
  • 每项更改及其对 Release 行为安全无虞的原因。
  • 用户可以运行以确认性能提升的修改前后命令。
  • 剩余的权衡：启用的实验性标志、基于策略假设移除的目标、工作线程限制，或推迟的生成代码工作。
  • 下面相关官方文档的链接。

官方文档

主题链接
提升 Kotlin/Native 编译速度https://kotlinlang.org/docs/native-improving-compilation-time.html
Kotlin Gradle 插件编译与缓存https://kotlinlang.org/docs/gradle-compilation-and-caches.html
iOS 集成方式https://kotlinlang.org/docs/multiplatform-ios-integration-overview.html
与 Xcode 直接集成https://kotlinlang.org/docs/multiplatform/multiplatform-direct-integration.html
构建最终 Native 二进制文件和 XCFrameworkhttps://kotlinlang.org/docs/multiplatform/multiplatform-build-native-binaries.html
Kotlin/Native 二进制选项https://kotlinlang.org/docs/native-binary-options.html
在 Kotlin Multiplatform 中使用 KSPhttps://kotlinlang.org/docs/ksp-multiplatform.html

评论

支持 Markdown