构建与依赖 / 知识点
Maven 实战操作指南
快速开始
确认 Maven、JDK 与 Wrapper 一致,避免本机和 CI 使用不同构建环境。
准备 Maven 构建环境
新接手项目、切换 JDK 或遇到“本地能构建、CI 失败”时先做这一步。目标是确认 Maven 实际使用的 JDK,并优先使用项目自带 Wrapper 固定 Maven 版本。
1. 检查实际运行环境
mvn -version预期看到 Maven 版本、Maven home 和 Java version。重点确认 Java version 与项目要求一致。
项目有 Wrapper 时继续执行:
./mvnw -versionWindows 使用:
.\mvnw.cmd -version2. 确认项目是否应使用 Wrapper
项目根目录存在 mvnw、mvnw.cmd 和 .mvn/wrapper/maven-wrapper.properties 时,后续构建优先使用 ./mvnw,不要混用全局 mvn。
3. 验证
./mvnw clean verify预期结果:
[INFO] BUILD SUCCESS若 Maven 使用了错误 JDK,优先检查 JAVA_HOME、IDE Maven 设置和 CI 环境变量。Wrapper 只固定 Maven,不负责切换 JDK。
使用固定 Archetype 创建标准 Maven Java 项目,并验证生成结果。
生成 Maven 项目骨架
需要从零创建一个标准 Maven Java 项目时使用。团队已有脚手架或模板仓库时,应优先使用团队模板。
创建项目
mvn -B archetype:generate \
-DgroupId=com.example \
-DartifactId=demo-app \
-Dversion=1.0.0-SNAPSHOT \
-Dpackage=com.example.app \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.5 \
-DinteractiveMode=false预期结果:
[INFO] BUILD SUCCESS随后确认 demo-app/pom.xml 已生成,并执行:
cd demo-app
mvn test注意
固定 Archetype 版本,避免不同时间生成不同项目结构。目标目录已存在时不要直接覆盖;先换到空目录生成并验证。
按 clean、test、package、verify 的正确范围完成日常验证或发布前构建。
完成一次标准构建
不知道该执行哪个 Maven 阶段时,用这条作为判断入口。
日常开发
只验证主源码:
mvn compile运行单元测试:
mvn test生成 JAR/WAR:
mvn package提交或发布前
推荐执行:
mvn clean verify预期结果:
[INFO] BUILD SUCCESSverify 会执行项目实际绑定到生命周期中的编译、测试、打包、集成测试和质量检查。
临时跳过测试
只跳过测试执行:
mvn clean package -DskipTests同时跳过测试编译和执行:
mvn clean package -Dmaven.test.skip=true后者验证范围更弱,不应作为提交或发布的默认命令。正式交付前重新执行不带跳过参数的 mvn clean verify。
把当前项目构件安装到本机 Maven 仓库,供其他本地项目按坐标引用。
安装构件到本地仓库
多个本地项目联调、下游项目需要引用当前尚未发布的 SNAPSHOT 时使用。
执行安装
mvn clean install预期输出包含:
[INFO] Installing <PATH>/target/<ARTIFACT>.jar to <LOCAL_REPO>/...
[INFO] BUILD SUCCESS安装后,下游项目即可按当前项目的 groupId:artifactId:version 解析该构件。
避免污染默认仓库
需要隔离验证时:
mvn -Dmaven.repo.local=<PATH> clean install不要用相同正式版本号反复安装不同内容,否则容易出现“本地正常、CI 失败”。多人共享构件应发布到团队制品仓库,而不是依赖个人 .m2。
通过受控配置把 SNAPSHOT 或 Release 构件安全发布到远程制品仓库。
发布构件到远程仓库
需要把构件提供给团队、CI 或生产部署流程时使用。正式版本优先由受保护的 CI 执行,不建议在个人电脑直接发布。
1. 配置发布目标
在 pom.xml 的 distributionManagement 中配置 Release 和 Snapshot 仓库;仓库 id 必须与 settings.xml 中的 <server><id> 一致。
2. 发布前验证
mvn clean verify必须先得到:
[INFO] BUILD SUCCESS3. 执行发布
mvn -B clean deploy预期输出包含:
[INFO] Uploading to <REPOSITORY_ID>: ...
[INFO] BUILD SUCCESS发布检查
确认上传的 groupId、artifactId、version 和目标仓库均正确。正式版本已经存在时不要覆盖或删除后重发,应提升版本号重新构建。
凭据放在 settings.xml、CI Secret 或密钥管理系统中,不要写入 POM、仓库 URL 或命令历史。
构建与模块
在多 POM、多模块工程中精确选择构建入口、目标模块及其上游依赖。
选择 POM 与目标模块
仓库包含多个 pom.xml,或只想构建部分模块时使用。
指定构建入口
mvn -f <PATH>/pom.xml verify只构建一个模块
从聚合根 POM 执行:
mvn -pl :order-service package连同上游依赖一起构建
mvn -pl :order-service -am verify预期输出:
[INFO] Reactor Build Order:
[INFO] <UPSTREAM_MODULE>
[INFO] order-service
...
[INFO] BUILD SUCCESS-pl 选择目标模块,-am 把当前 Reactor 中该模块依赖的上游模块一并加入。
如果出现 Could not find the selected project in the reactor,先确认当前使用的是正确的聚合 POM,并检查目标模块是否被当前 Profile 纳入 <modules>。
修复多模块构建失败后,从指定模块继续,避免重复执行已成功模块。
从失败模块继续构建
大型 Reactor 在中途失败、问题已经修复时使用。
假设原命令为:
mvn install -Pci失败模块是 order-service,修复后执行:
mvn install -Pci -rf :order-service预期结果:
[INFO] order-service ........................ SUCCESS
[INFO] BUILD SUCCESS上游构件缺失时
-rf 不会自动重建失败模块之前的项目。若新进程找不到上游构件,先执行:
mvn install -Pci -pl :order-service -am如果前置模块也发生了修改,直接重新执行完整 Reactor 更安全。恢复构建时保留原命令中的 Profile、属性和 Settings 参数。
在一次构建中切换环境配置、功能开关或插件参数,并确认最终生效值。
使用 Profile 与构建属性
需要临时切换环境、功能开关或插件配置时使用。它们只影响当前 Maven 进程,不会自动修改 POM。
传递属性
mvn -Dbuild.env=staging test验证 Maven 收到的值:
mvn -q help:evaluate \
-Dexpression=build.env \
-Dbuild.env=staging \
-DforceStdout预期输出:
staging激活 Profile
mvn clean verify -Pdev,integration-test显式禁用 Profile:
mvn clean verify '-Pdev,!prod'确认最终激活结果:
mvn help:active-profiles '-Pdev,!prod'不要通过 -Dpassword=... 或 -Dtoken=... 传递密钥;命令可能进入 shell 历史、进程列表和 CI 日志。
为 CI 使用非交互、低噪声和可控并行度的 Maven 构建方式。
配置 CI 构建参数
CI/CD 中建议关闭交互和下载进度,并根据资源限制设置并行度。
推荐基线
mvn -B -ntp -V -Dstyle.color=never clean verify预期结果:
Apache Maven <MAVEN_VERSION>
[INFO] BUILD SUCCESS-B 禁止交互,-ntp 隐藏传输进度,-V 打印 Maven 版本。
多模块并行
先从保守并行度开始:
mvn -T 2 -B -ntp clean verify确认稳定后再评估 -T 1C。如果只在并行构建时出现随机测试失败、文件覆盖或 OOM,先去掉 -T 验证串行基线,再检查共享端口、共享目录和插件线程安全性。
在无网络环境使用缓存构建,或在 SNAPSHOT 异常时主动重新检查远程仓库。
离线构建与刷新快照
这两个动作目标相反:离线模式禁止访问远程仓库,-U 强制重新检查远程更新,不要同时使用。
离线构建
mvn -o clean verify出现 BUILD SUCCESS 表示当前命令所需依赖和插件都已在本地缓存。
若缓存不完整,先联网执行一次与目标环境相同的构建,再重新离线验证。
刷新 SNAPSHOT
本地仍使用旧 SNAPSHOT 或存在负缓存时:
mvn -U clean verify若怀疑本地 JAR 已损坏,-U 不一定能修复,应按具体坐标清理缓存,而不是删除整个 .m2/repository。
展开最终 POM 与 Settings,确认继承、Profile、镜像、仓库和代理实际采用了什么配置。
查看 Maven 生效配置
当“配置明明写了却没有生效”时,先看最终模型,不要只检查源文件。
查看生效 POM
mvn help:effective-pom -Dverbose -Doutput=effective-pom.xml重点检查依赖版本、插件配置、Profile 合并结果和配置来源。
查看生效 Settings
mvn help:effective-settings -Doutput=effective-settings.xml重点检查:
<localRepository><mirrors><servers><proxies><activeProfiles>
复现 CI 问题时必须使用与 CI 相同的 Wrapper、-s、-gs、Profile 和环境变量。
输出文件可能包含内部仓库地址、用户名和本地路径,排障完成后及时删除,不要提交到 Git。
依赖管理
定位某个依赖由谁引入、最终选择了哪个版本,以及冲突节点来自哪条路径。
分析依赖树与引入路径
遇到版本覆盖、类冲突或“不知道谁引入了这个包”时使用。
查看完整依赖树
mvn dependency:tree定位单个依赖
mvn dependency:tree \
-Dincludes='com.fasterxml.jackson.core:jackson-databind' \
-Dverbose预期会保留目标依赖及其祖先路径。出现:
omitted for conflict with <VERSION>表示该节点没有被最终采用。
只看运行期依赖
mvn dependency:tree -Dscope=runtime多模块工程应在实际故障模块执行,或使用 -pl <MODULE> 缩小范围。过滤结果为空时,先移除过滤条件,避免因为坐标、作用域或 Profile 写错而误判。
发现未显式声明、疑似未使用的依赖,并生成可升级版本清单。
检查依赖声明与可用更新
适合依赖治理和升级前盘点,不建议把检查结果直接当作自动修改依据。
检查声明问题
mvn -DskipTests dependency:analyze重点看:
Used undeclared dependencies found
Unused declared dependencies foundUsed undeclared 通常应补成直接依赖;Unused declared 可能受反射、SPI、驱动或框架自动配置影响,删除前必须完整验证。
查看可升级版本
mvn org.codehaus.mojo:versions-maven-plugin:2.21.0:display-dependency-updates \
-DallowSnapshots=false先生成清单,再按依赖族分批升级;每批修改后执行 mvn clean verify。发现新版本不代表可以无风险升级。
通过 BOM、dependencyManagement 和精确 exclusions 收敛版本并消除不需要的传递依赖。
统一依赖版本并处理冲突
依赖树中出现同一组件多个版本、NoSuchMethodError 或运行期类冲突时,先确认实际胜出的版本,再选择处理方式。
1. 先定位冲突
mvn dependency:tree -Dverbose \
-Dincludes='<GROUP_ID>:<ARTIFACT_ID>'2. 同一组件族需要统一版本
优先在父 POM 的 dependencyManagement 中统一版本;组件提供 BOM 时可导入 BOM:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.junit</groupId>
<artifactId>junit-bom</artifactId>
<version>5.10.2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>3. 某条路径不需要传递依赖
在产生该路径的直接依赖下精确排除:
<exclusions>
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>最后重新执行依赖树和 mvn clean verify。不要为了消除冲突盲目排除仍被运行时使用的组件。
将未发布到远程仓库的外部 JAR 按 Maven 坐标安装到本地仓库。
安装第三方 JAR
只有外部 JAR 无法从任何可访问仓库获取时才使用。团队长期使用应发布到内部制品仓库。
安装
mvn org.apache.maven.plugins:maven-install-plugin:3.1.4:install-file \
-Dfile=./lib/vendor-sdk-1.2.3.jar \
-DgroupId=com.vendor \
-DartifactId=vendor-sdk \
-Dversion=1.2.3 \
-Dpackaging=jar \
-DgeneratePom=true预期结果:
[INFO] BUILD SUCCESS验证
mvn org.apache.maven.plugins:maven-dependency-plugin:3.11.0:get \
-Dartifact=com.vendor:vendor-sdk:1.2.3 \
-Dtransitive=false供应商提供真实 POM 时优先使用 -DpomFile=<PATH>,否则传递依赖不会自动补齐。不要用相同坐标反复安装不同二进制。
只清理异常坐标并重新解析,避免粗暴删除整个 Maven 本地仓库。
修复本地依赖缓存
同一个依赖持续报损坏、.lastUpdated 异常或下载中断时使用。
先确认目标坐标
mvn dependency:tree \
-Dincludes='<GROUP_ID>:<ARTIFACT_ID>'精确清理并重新解析
mvn dependency:purge-local-repository \
-DmanualInclude=<GROUP_ID>:<ARTIFACT_ID> \
-DreResolve=true预期结果:
[INFO] BUILD SUCCESS随后重新执行原构建命令验证。
不要把 rm -rf ~/.m2/repository 当作常规排障手段。全量删除会扩大下载范围、破坏离线能力,并可能把一个小问题变成仓库或网络故障。
环境与仓库配置
在父 POM 中显式管理插件版本,减少不同 Maven 环境导致的构建漂移。
锁定构建插件版本
需要可重复构建或多模块统一插件版本时使用。
推荐做法
在父 POM 的 pluginManagement 中集中管理版本:
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
</plugin>
</plugins>
</pluginManagement>需要实际执行的插件仍应在 <plugins> 中引用。
验证
mvn help:effective-pom -Doutput=effective-pom.xml在输出中搜索目标 artifactId,确认最终 <version> 正确。
插件升级可能改变最低 JDK/Maven 要求和默认行为,应独立升级并执行完整验证,不要一次性批量提升所有插件版本。
使用 maven.compiler.release 统一源码语言级别、标准库 API 和目标字节码版本。
设置 Java 编译版本
项目需要明确目标 Java 版本时使用。JDK 9 及以上优先使用 release。
配置
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>验证
mvn -version
mvn clean compile预期 Maven 使用的 JDK 不低于目标版本,并以:
[INFO] BUILD SUCCESS结束。
若出现 release version <N> not supported,先检查 mvn -version 显示的 JDK,而不是只看 java -version。不要同时维护互相矛盾的 release、source 和 target。
让 Maven 插件使用指定 JDK,而不依赖当前启动 Maven 的 JAVA_HOME。
配置 JDK Toolchains
同一机器安装多个 JDK,或项目需要“用一个 JDK 启动 Maven、用另一个 JDK 编译/测试”时使用。
1. 配置 toolchains.xml
在 ~/.m2/toolchains.xml 中声明可用 JDK,例如:
<toolchains>
<toolchain>
<type>jdk</type>
<provides>
<version>17</version>
</provides>
<configuration>
<jdkHome>/path/to/jdk-17</jdkHome>
</configuration>
</toolchain>
</toolchains>2. 在项目中声明工具链需求
由项目使用的 Toolchains、Compiler、Surefire 等插件读取所需 JDK。
3. 验证
执行项目原有的:
mvn clean verify并检查构建日志中实际选择的 JDK。
Toolchains 不等于修改系统 JAVA_HOME。路径不存在、权限不足或版本条件不匹配时,插件可能找不到工具链。
在构建时替换非敏感资源变量,并通过生成文件验证最终值。
配置资源变量替换
需要把项目版本、环境名等非敏感值写入资源文件时使用。
配置独立过滤目录
<resource>
<directory>src/main/resources-filtered</directory>
<filtering>true</filtering>
</resource>资源文件中:
app.name=${project.artifactId}
app.version=${project.version}
env.name=${env.name}构建并验证
mvn -q -Denv.name=staging process-resources
cat target/classes/build-info.properties预期:
env.name=staging不要对 PNG、JAR、ZIP、字体等二进制文件启用过滤,也不要把密码和令牌写进 POM 或过滤后的制品。