如何解决命令行编译运行依赖外部JAR的Kotlin文件时的unresolved reference报错

常见报错诱因与排查方法 #

• 路径匹配偏差：执行kotlinc命令的终端当前工作目录，必须和-cp参数填写的B.jar路径完全对应。如果B.jar存放在子目录（比如当前目录下的libs文件夹），classpath参数要写为-cp ./libs/B.jar，路径错位会导致编译器完全扫描不到jar内的类。
• 缺少对应import语句：执行jar tf B.jar命令列出jar包内的类文件路径，如果B类的实际路径是带包名的（比如com/test/B.class），必须在A.kt的代码头部加上对应的导入语句import com.test.B，否则哪怕classpath配置正确，也会触发引用找不到的报错。
• 运行阶段classpath漏配：编译期配置的jar依赖不会自动带入运行环节，后续执行编译产物时，必须把B.jar也加入运行命令的classpath参数里。注意不同系统的classpath分隔符差异：Linux/macOS用冒号:分隔，Windows用分号;分隔。
• jar包本身异常：如果B.jar存在文件损坏、是由更高版本Kotlin编译生成的、或者不是标准的可识别jar结构，也会导致类引用失败，可重新导出完整的有效jar包重试。

完整正确操作示例 #

假设B.jar存放在当前工作目录，且内部的B类位于org.demo包下：

1. 先校验jar内的类路径：

   jar tf B.jar | grep "B.class"
   # 正常输出格式为：org/demo/B.class
   

2. 在A.kt代码头部补充导入语句：

   import org.demo.B
   

3. 执行带依赖的编译命令，直接生成可运行的jar包：

   kotlinc A.kt -cp B.jar -include-runtime -d app.jar
   

4. 执行对应系统的运行命令：

   # Linux/macOS 执行命令
   kotlin -cp app.jar:B.jar appKt
   

   # Windows 执行命令
   kotlin -cp app.jar;B.jar appKt
   

内容的提问来源于stack exchange，提问作者Vishisht Tiwari