在没有图形界面的服务器上跑 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。平台安装方式备注macOSbrew install kotlin需要先装 HomebrewWindowschoco install kotlin或scoop install kotlin需要以管理员权限运行或用用户级 scoop 安装Linux下载官方 zip 包解压后配置 PATH官网 releases 页拿最新版任意平台推荐SDKMANsdk install kotlinLinux/macOS 都能用版本切换很方便我个人的推荐顺序是macOS 直接用 HomebrewWindows 用 ScoopLinux 用 SDKMAN。尽量别去 apt 源装太老的版本因为后面第 5 节会讲到Kotlin 编译器版本如果太旧连编译一些新库都会报警告。Linux 里如果你愿意也可以直接下载官方的 zip 包解压到/opt/kotlin再把bin目录写进.bashrc的PATH这种手动方式最透明也最不容易被系统包管理器影响。装完之后验证一下kotlinc -version正常情况下会输出类似info: kotlinc-jvm 2.0.20 (JRE 17.0.107)的信息。若报错九成是JAVA_HOME没配好因为kotlinc脚本会去JAVA_HOME里找 Java 可执行文件。2.2 第一个 hello worldkotlinc 参数逐个拆解新建一个hello.kt文件fun main() { println(Hello from command line!) }然后执行kotlinc hello.kt -include-runtime -d hello.jar java -jar hello.jar这是整个 Kotlin 命令行编译里最经典的一条命