CANN/ge GetLocation API
2026/9/10 6:34:40
在没有图形界面的服务器上跑 Kotlin 编译任务，是我今年踩坑最多、也收获最大的一段经历。你以为 Kotlin 编译就是 IDE 里点一下按钮，但当你真正面对一个kotlinc命令行、一份 classpath、一堆版本号的时候，才会发现 IDE 替你藏掉了多少细节。这篇攻略我就把 Kotlin 命令行编译从环境准备到多文件项目、从依赖处理到版本兼容、再到 Android 场景的完整链路整理出来，都是实操过的东西。适合刚学 Kotlin 想弄懂编译过程的人，也适合要在 CI 或容器里加编译任务的工程师，更建议正在被各种 "incompatible version" 报错折磨的朋友重点看第 5 节。
1. 为什么要把 Kotlin 编译搬到命令行：三个让我回不去的场景
1.1 IDE 之外的硬需求
我先说结论：日常开发里 IDE 仍然是最高效的，但命令行编译绝不是什么倒退。我遇到的第一类需求是 CI/CD。公司内部跑流水线的那台 Linux 机器没有装图形环境，每次代码合并后要自动拉代码、编译、跑测试、出报告，总不能指望从 Jenkins 里启动 Android Studio。命令行编译是唯一稳定的自动化方式。
第二类是容器化。程序打包成 Docker 镜像的时候，Dockerfile 里要执行的编译命令也是纯命令行的。你没法在镜像构建阶段点 IDE 的 Run 按钮，只能老老实实写kotlinc或gradle命令。第三类是临时验证和教学。有时候我只想快速验证一段 Kotlin 语法、一个协程行为，或者要给学生写一个最小可复现的例子，开 IDE 建工程太重了，命令行几秒钟就能搞定。
1.2 命令行编译真正教会我的事
IDE 最大的问题不是慢，而是把关键细节隐藏得太好。你有没有想过，点击 Build 的时候 IDE 到底做了哪几步？我过去长期被 IDE 惯着，从来没认真理解过 classpath、编译产物、运行时这几个概念，直到项目里出现 "Module was compiled with an incompatible version of Kotlin" 这个报错，我才发现自己在 IDE 里点了无数遍构建，却连"Kotlin 编译器版本"和"库的 metadata 版本"是两回事都不清楚。命令行编译逼着我把每个参数、每条命令写出来，反而让我把编译原理层面的东西理顺了。
从这时候起，我就养成了一个习惯：任何 Kotlin 项目，我都会先确认它能不能脱离 IDE 在命令行编译通过。能通过，说明项目的构建配置是干净、可复现的；不能通过，那 IDE 里大概率也埋着隐患。
1.3 这篇攻略的组织方式
下面我按照一个新手从零开始的路径来写：第 2 节先把kotlinc的环境和单个文件编译跑通；第 3 节扩展到多文件项目和包结构；第 4 节重点讲命令行模式下最让人头疼的第三方依赖问题；第 5 节是这种模式下最高频的版本兼容类报错的完整排查思路；第 6 节专门聊 Android 开发中命令行编译的真实形态。每一节都保留了我在实际操作中的原始命令和踩坑记录，你可以直接复制去用，也可以顺着我的排查路径走一遍。
2. 安装 kotlinc：三个平台的环境准备与第一个编译命令
2.1 各平台安装方式与前置依赖
kotlinc是 Kotlin 官方提供的纯命令行编译器，不依赖任何 IDE。它在 macOS、Windows、Linux 上都能跑，但在动手装之前，请先确认机器上有 JDK。Kotlin/JVM 编译产物最终运行在 JVM 上，所以 JDK 是硬前提。我的习惯是在终端先跑一句java -version，如果提示找不到命令，先去装 JDK；如果显示的不是 OpenJDK 或 Oracle JDK，而是 JRE，也别急着高兴，因为kotlinc在编译期会用到javac相关的工具类，建议直接装完整的 JDK。
| 平台 | 安装方式 | 备注 |
|---|---|---|
| macOS | brew install kotlin | 需要先装 Homebrew |
| Windows | choco install kotlin或scoop install kotlin | 需要以管理员权限运行，或用用户级 scoop 安装 |
| Linux | 下载官方 zip 包解压后配置 PATH | 官网 releases 页拿最新版 |
| 任意平台（推荐） | SDKMAN：sdk install kotlin | Linux/macOS 都能用，版本切换很方便 |
我个人的推荐顺序是：macOS 直接用 Homebrew，Windows 用 Scoop，Linux 用 SDKMAN。尽量别去 apt 源装太老的版本，因为后面第 5 节会讲到，Kotlin 编译器版本如果太旧，连编译一些新库都会报警告。Linux 里如果你愿意，也可以直接下载官方的 zip 包，解压到/opt/kotlin，再把bin目录写进.bashrc的PATH，这种手动方式最透明，也最不容易被系统包管理器影响。
装完之后验证一下：
kotlinc -version正常情况下会输出类似info: kotlinc-jvm 2.0.20 (JRE 17.0.10+7)的信息。若报错，九成是JAVA_HOME没配好，因为kotlinc脚本会去JAVA_HOME里找 Java 可执行文件。
2.2 第一个 hello world：kotlinc 参数逐个拆解
新建一个hello.kt文件：
fun main() { println("Hello from command line!") }然后执行：
kotlinc hello.kt -include-runtime -d hello.jar java -jar hello.jar这是整个 Kotlin 命令行编译里最经典的一条命