本文详解如何通过命令行统一运行含外部依赖的 Java 程序，兼容 Windows 与 Linux 环境，涵盖 java -jar 失败排查、-cp 正确用法、跨平台类路径分隔符处理，以及构建可移植可执行 JAR 的最佳实践。
本文详解如何通过命令行统一运行含外部依赖的 java 程序，兼容 windows 与 linux 环境，涵盖 `java -jar` 失败排查、`-cp` 正确用法、跨平台类路径分隔符处理，以及构建可移植可执行 jar 的最佳实践。
在实际开发与 CI/CD（如 Jenkins）场景中，常需通过命令行直接运行一个含第三方库（如 Apache HttpClient、JUnit、Gson 等）的 Java 主类（例如 APITestRunner）。但直接执行 java -jar test.jar 却报错 Could not find or load main class APITestRunner 或 ClassNotFoundException，根本原因通常是：JAR 未正确声明依赖或主类入口。
✅ 首先诊断 JAR 是否具备可执行能力
解压你的 test.jar（可用 jar -tf test.jar 或直接用归档工具打开），检查 META-INF/MANIFEST.MF 文件内容。关键看是否存在以下两项：
Main-Class: my.package.APITestRunner Class-Path: lib/gson-2.10.1.jar lib/commons-io-2.11.0.jar
- 若缺失 Main-Class：JVM 不知从哪启动，必须显式指定类名；
- 若缺失 Class-Path：所有依赖不会被自动加载，需手动拼接 -cp。
? 提示：IntelliJ 打包时默认不写 Class-Path；Gradle/Maven 构建可配置 maven-jar-plugin 或 application 插件自动生成。
✅ 方案一：使用 -cp 显式指定类路径（推荐用于多环境调试）
将所有依赖 JAR 统一放入 lib/ 目录（与 test.jar 同级），然后按平台拼接类路径：
-
Linux/macOS（用冒号 : 分隔）：
java -cp "test.jar:lib/*" my.package.APITestRunner
-
Windows（用分号 ; 分隔）：
java -cp "test.jar;lib\*" my.package.APITestRunner
✅ lib/* 是 JDK 6+ 支持的通配符语法（注意：仅匹配 JAR，不递归子目录），大幅简化路径书写；且 * 前的 / 或 \ 在各自系统下均可工作（Windows 也支持 /）。
⚠️ 注意事项：
- java -cp 后不能加 -jar —— 二者互斥；
- 类名必须是全限定名（含包路径），如 my.package.APITestRunner，而非 APITestRunner.java；
- 确保 my/package/APITestRunner.class 确实存在于 test.jar 的对应路径下（可用 jar -tf test.jar | grep APITestRunner 验证）；
- 若依赖中存在 slf4j-api.jar 但缺少 slf4j-simple.jar，仍会运行时报 NoClassDefFoundError —— 请确保 lib/ 下包含全部运行时依赖（建议用 Maven 的 dependency:copy-dependencies 或 Gradle 的 copyLibs 任务预处理）。
✅ 方案二：构建真正可跨平台的可执行 JAR（推荐用于 Jenkinsfile）
为实现“一次构建，处处运行”，应生成带 Main-Class 和 Class-Path 的标准可执行 JAR。以 Maven 为例，在 pom.xml 中配置：
<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-jar-plugin</artifactid><version>3.3.0</version><configuration><archive><manifest><addclasspath>true</addclasspath><classpathprefix>lib/</classpathprefix><mainclass>my.package.APITestRunner</mainclass></manifest></archive></configuration></plugin>
再配合 maven-dependency-plugin 将依赖复制到 lib/：
<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-dependency-plugin</artifactid><executions><execution><id>copy-dependencies</id><phase>prepare-package</phase><goals><goal>copy-dependencies</goal></goals><configuration><outputdirectory>${project.build.directory}/lib</outputdirectory></configuration></execution></executions></plugin>
构建后执行 mvn clean package，即可得到：
- target/your-app.jar（含正确 MANIFEST）
- target/lib/*.jar（所有依赖）
此时无论 Windows 还是 Linux，均可统一执行：
java -jar target/your-app.jar
✅ Jenkinsfile 中的安全调用建议
sh 'java -cp "target/test.jar:target/lib/*" my.package.APITestRunner' // Linux agent
// 或统一用脚本封装（更健壮）
sh '''
if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" ]]; then
java -cp "target/test.jar;target/lib/*" my.package.APITestRunner
else
java -cp "target/test.jar:target/lib/*" my.package.APITestRunner
fi
'''
总结
| 场景 | 推荐方式 | 跨平台性 | 维护成本 |
|---|---|---|---|
| 本地快速验证 | -cp "app.jar:lib/*" + 全限定类名 | ⚠️ 需条件分支 | 低 |
| Jenkins 自动化部署 | 构建含 MANIFEST.MF 的可执行 JAR | ✅ java -jar 一行通吃 | 中（需配置构建插件） |
| IntelliJ 调试 | 直接 Run Configuration → 设置 Classpath 和 Main class | ✅（IDE 自动处理） | 零 |
最终，避免 javac 编译失败（package does not exist）的关键，是始终以已编译好的类/ JAR 为运行起点，而非源码 —— 命令行运行阶段只需 java，无需 javac。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
