Java JAR 包「找不到主類」終極排查指南

現象描述

使用 JarOutputStream 手動打包 JAR，Manifest 包含 Main-Class、Class-Path、版本號等屬性。解壓對比發現：自動打包與手動打包的 JAR 大小相同、所有文件二進制內容完全一致，但執行 java -jar xxx.jar 時自動打包版報錯「找不到主類」。

根本原因

ZIP 条目路徑分隔符不一致：

• Java 規範要求 JAR 內部路徑必須使用正斜杠 `/`
• Windows 環境下手動寫入 ZipEntry 時若使用反斜杠 `\`，解壓工具（如 7-Zip、WinRAR）雙向兼容，但 JVM 類加載器只識別 `/`
• 導致類文件在 JAR 內實際路徑為 test\Helloworld.class，而類加載器查找 test/Helloworld.class，從而找不到主類

代碼對比

錯誤寫法（Windows 路徑分隔符）

String className = "test.Helloworld";
String entryName = className.replace('.', File.separatorChar) + ".class"; // 產生 "test\Helloworld.class"
ZipEntry entry = new ZipEntry(entryName);
jarOut.putNextEntry(entry);

正確寫法（強制使用正斜杠）

String className = "test.Helloworld";
String entryName = className.replace('.', '/') + ".class"; // 固定產生 "test/Helloworld.class"
ZipEntry entry = new ZipEntry(entryName);
jarOut.putNextEntry(entry);

驗證方法

# 查看 JAR 內部路徑分隔符
jar tf your.jar | head -20
# 正確輸出應為：
# META-INF/
# META-INF/MANIFEST.MF
# test/Helloworld.class

最佳實踐建議

1. 統一使用 Apache Ant / Maven / Gradle 等構建工具打包，避免手動操作 JAR
2. 若必須手動打包，路徑處理永遠使用 `/`，不可依賴 File.separator 或 File.separatorChar
3. Manifest 中 Class-Path 同樣要求使用正斜杠分隔
4. 編寫單元測試驗證：new JarFile(jar).entries().asIterator().allMatch(e -> !e.getName().contains("\\"))

擴展知識

JAR 格式本質是 ZIP 文件，但 JAR 規範 明確要求：

「所有路徑名稱必須使用正斜杠 `/` 作為分隔符，與平台無關。」

這也是 Java「一次編寫，到處運行」在打包層面的體現。