
本文详解如何在不依赖 IDE 的纯命令行环境下,正确运行含依赖的 Maven 项目,涵盖 mvn exec:java、mvn dependency:copy-dependencies、可执行 Fat JAR 打包等核心方案,并给出 Docker 构建中的标准化实践。
本文详解如何在不依赖 ide 的纯命令行环境下,正确运行含依赖的 maven 项目,涵盖 `mvn exec:java`、`mvn dependency:copy-dependencies`、可执行 fat jar 打包等核心方案,并给出 docker 构建中的标准化实践。
在 Maven 项目中,直接通过 java -cp target/xxx.jar MainClass 运行程序却遭遇 NoClassDefFoundError,本质是手动绕过了 Maven 的依赖解析机制——.m2/repository 是一个结构化仓库(按 groupId/artifactId/version/ 分层存储),而非扁平化的 JAR 集合,因此无法用通配符(如 -cp ~/.m2/repository/**/*jar)或简单目录路径加载全部依赖。正确的做法是让 Maven 主动生成并管理运行时类路径,而非人工拼接。
✅ 推荐方案一:使用 exec-maven-plugin 直接运行(开发调试首选)
在 pom.xml 中配置插件,声明主类:
<build><plugins><plugin><groupid>org.codehaus.mojo</groupid><artifactid>exec-maven-plugin</artifactid><version>3.4.1</version><configuration><mainclass>com.example.App</mainclass><!-- 可选:传递 JVM 参数 --><systemproperties><systemproperty><key>log.level</key><value>DEBUG</value></systemproperty></systemproperties></configuration></plugin></plugins></build>
执行命令即可一键运行(自动包含所有 compile 范围依赖):
mvn compile exec:java
✅ 优势:零配置 CLASSPATH,支持热重载调试(配合
exec:java -Dexec.args="-agentlib:jdwp..."),适用于本地快速验证。
✅ 推荐方案二:生成完整类路径字符串(轻量脚本化场景)
mvn dependency:build-classpath 确实是官方支持的方案,但无需手动拼接——可结合 shell 命令自动完成:
# Linux/macOS java -cp "$(mvn dependency:build-classpath -Dmdep.outputFile=/dev/stdout | tr '\n' ':')$(pwd)/target/my-app-1.0-SNAPSHOT.jar" com.example.App # 或更清晰的两步法(推荐) CP=$(mvn dependency:build-classpath -Dmdep.outputFile=/dev/stdout | tr '\n' ':') java -cp "$CP:$(pwd)/target/my-app-1.0-SNAPSHOT.jar" com.example.App
⚠️ 注意事项:
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
- Windows 用户需用
mvn dependency:build-classpath -Dmdep.outputFile=cp.txt && set /p CP= - 此方式生成的 classpath 仅包含
compile和runtime范围依赖(默认排除test和provided),符合生产运行语义。
✅ 推荐方案三:构建可执行 Fat JAR(Docker / 发布部署首选)
对 Docker 或分发场景,应打包为自包含的可执行 JAR(含所有依赖 + 正确 MANIFEST.MF)。推荐使用 maven-shade-plugin(比 assembly 更成熟,支持类重定位防冲突):
<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-shade-plugin</artifactid><version>3.5.0</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><transformers><transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainclass>com.example.App</mainclass></transformer></transformers><!-- 可选:解决 META-INF 文件冲突 --><filters><filter><artifact>*:*</artifact><excludes><exclude>META-INF/*.SF</exclude><exclude>META-INF/*.DSA</exclude><exclude>META-INF/*.RSA</exclude></excludes></filter></filters></configuration></execution></executions></plugin>
构建后执行:
mvn clean package java -jar target/my-app-1.0-SNAPSHOT.jar # 无需额外 classpath
? Docker 构建最佳实践
Dockerfile 应遵循 “构建阶段分离”原则,避免将 .m2 仓库打入镜像:
# 构建阶段:利用 Maven 缓存加速 FROM maven:3.9.16-openjdk-17-slim AS build WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline -B # 预下载依赖(提升后续缓存命中率) COPY src ./src RUN mvn clean package -DskipTests # 运行阶段:极简基础镜像 FROM openjdk:17-jre-slim WORKDIR /app COPY --from=build /app/target/my-app-1.0-SNAPSHOT.jar app.jar ENTRYPOINT ["java", "-jar", "app.jar"]
✅ 关键点:
- 使用多阶段构建,最终镜像不含 Maven、源码、编译工具链;
mvn dependency:go-offline提前拉取依赖,使pom.xml变更时仅重建该层;- 不挂载
.m2卷到容器——这会破坏构建可重现性。
❌ 不推荐的做法(避坑提醒)
-
引入本地 JAR:破坏可移植性,CI/CD 失败,Maven 3.9+ 已标记为过时;system -
手动
export CLASSPATH=...指向.m2/repository:路径层级嵌套,无法匹配坐标依赖关系,必然失败; -
在
settings.xml中修改后期望 JVM 自动识别:JVM 完全不读取 Maven 配置,此路径仅对 Maven 进程生效。
总结:Maven 的设计哲学是“约定优于配置”。与其对抗其仓库模型,不如用 exec:java 调试、用 shade 打包、用多阶段 Dockerfile 发布——每一步都由 Maven 原生能力保障一致性与可重现性。










