构建与依赖 / 知识点
Maven 实战操作指南
环境与仓库配置
为 CI 或排障临时指定独立本地仓库,验证构建是否依赖个人缓存。
隔离本地 Maven 仓库
需要复现干净机器、避免 CI 作业污染默认缓存或验证缓存问题时使用。
使用独立目录
mvn -Dmaven.repo.local=<PATH> clean verify确认实际路径
mvn -Dmaven.repo.local=<PATH> \
help:evaluate \
-Dexpression=settings.localRepository \
-q -DforceStdout预期输出目标仓库的绝对路径。
空仓库首次构建会重新下载依赖和插件,这是正常现象。并发 CI 作业不要写入同一个共享仓库目录;每个作业使用独立目录,再交给 CI 缓存机制复用。
通过 settings.xml 把外部仓库统一转发到 Nexus、Artifactory 等内部镜像。
配置 Maven 仓库镜像
公司要求依赖统一经过内部仓库管理器时使用。
配置
在 ~/.m2/settings.xml 中:
<mirrors>
<mirror>
<id>corp-mirror</id>
<url>https://repo.example.com/repository/maven-public/</url>
<mirrorOf>*</mirrorOf>
</mirror>
</mirrors>只代理 Central 时使用 central;需要排除某个仓库时使用类似 *,!internal-releases。mirrorOf 匹配的是仓库 ID,不是 URL。
验证
mvn -U dependency:resolve下载日志应显示:
Downloading from corp-mirror: ...优先使用 HTTPS。不要通过关闭 TLS 校验、信任所有证书或改用裸 HTTP 来“解决”仓库问题。
让 Maven 在必须经过企业代理的网络环境中正常访问外部仓库。
配置 Maven 网络代理
操作系统能联网但 Maven 访问外部仓库超时,且公司网络要求代理时使用。
在 ~/.m2/settings.xml 中配置:
<proxies>
<proxy>
<id>corp-proxy</id>
<active>true</active>
<protocol>http</protocol>
<host>proxy.example.com</host>
<port>8080</port>
<nonProxyHosts>localhost|127.0.0.1|*.corp.example.com</nonProxyHosts>
</proxy>
</proxies>验证
mvn help:effective-settings
mvn -U dependency:resolve出现 407 Proxy Authentication Required 时检查代理认证;内部仓库不应走代理时,把域名加入 nonProxyHosts。
若代理执行 HTTPS 解密并触发 PKIX path building failed,应把企业 CA 导入 Maven 所用 JDK 的信任库,而不是关闭 TLS 校验。
为私有仓库下载和发布配置凭据,并避免凭据进入源码和日志。
配置仓库认证
私服返回 401/403,或发布任务需要认证时使用。
配置 server
settings.xml 中的 id 必须与仓库、镜像或 distributionManagement 使用的 ID 完全一致:
<servers>
<server>
<id>private-releases</id>
<username>${env.REPO_USER}</username>
<password>${env.REPO_PASSWORD}</password>
</server>
</servers>验证
mvn help:effective-settings -DshowPasswords=false确认目标 <server><id> 存在,再执行一次只读依赖解析或实际发布任务。
Maven 3 的密码加密可以降低明文暴露风险,但不能替代短期令牌、最小权限和 CI Secret。不要把密钥放进 POM、仓库 URL 或 -Dpassword=...。
故障排查
按网络、认证和 TLS 三条路径快速定位依赖下载或制品上传失败。
排查 Maven 仓库访问失败
出现依赖下载失败、401/403、超时或 PKIX path building failed 时,按错误类型分支处理。
先确认实际访问哪个仓库
mvn -X dependency:resolve只在受控环境临时使用 -X,日志可能包含内部地址和敏感参数。
401 / 403
检查:
settings.xml中<server><id>是否与仓库或镜像 ID 一致。- 账号或令牌是否过期。
- 账号是否具备目标仓库的读写权限。
401 通常表示认证失败;403 通常表示已识别身份但权限不足。
超时 / UnknownHost
检查 DNS、代理、防火墙、镜像 URL 和仓库服务状态。
PKIX / SSL
确认 Maven 实际使用的 JDK:
mvn -version把正确的企业 CA 或仓库证书链导入该 JDK 信任库。不要使用跳过证书校验参数作为长期解决方案。
在普通错误不足以定位时保存异常链和 DEBUG 日志,并从首个失败目标向下分析。
输出并读取 Maven 调试日志
构建只显示 BUILD FAILURE 或错误链不完整时,先使用 -e,仍无法定位再使用 -X。
保存日志
mvn -e -X -l maven-debug.log clean verify优先搜索:
[ERROR]
Failed to execute goal
Caused by:读取顺序:
- 找到第一个失败模块和插件目标。
- 从最后一个有业务意义的
Caused by:确认根因。 - 再回看对应插件的配置、仓库或测试上下文。
-X 日志可能暴露仓库地址、本地路径、用户名和插件参数。共享前必须脱敏,不要把 DEBUG 作为 CI 默认日志级别。
从 Surefire/Failsafe 报告定位首个失败测试,并区分断言失败与测试执行异常。
排查 Maven 测试失败
mvn test 或 mvn verify 失败时,不要只看最后一行 BUILD FAILURE。
1. 查看汇总
关注:
Tests run: <N>, Failures: <N>, Errors: <N>, Skipped: <N>Failures 通常是断言失败,Errors 通常是测试执行异常。
2. 查看详细报告
单元测试:
target/surefire-reports/集成测试:
target/failsafe-reports/3. 单独复现
mvn -Dtest=OrderServiceTest test或:
mvn -Dtest=OrderServiceTest#shouldCreateOrder test先解决第一个稳定失败用例。只在并行或 CI 中失败时,再比较 JDK、Profile、环境变量、时区、端口和外部依赖环境。
定位 Maven 使用的 JDK、编译目标版本和运行时 JRE 之间的不一致。
排查 Java 版本不匹配
出现 invalid target release、release version not supported 或 UnsupportedClassVersionError 时使用。
先看 Maven 实际 JDK
mvn -version不要只看:
java -version因为 Maven 可能通过 JAVA_HOME、IDE 或 CI 使用另一个 JDK。
判断方向
release version <N> not supported:构建 JDK 太旧。invalid target release:常见于旧 JDK、旧编译插件或最终 POM 被覆盖。UnsupportedClassVersionError:运行时 JRE 低于已生成 class 的版本。
继续执行:
mvn help:effective-pom -Doutput=effective-pom.xml确认最终 maven.compiler.release 和 Compiler Plugin 配置。修正 JDK 或目标版本后执行 mvn clean verify。
区分 Maven 主 JVM、测试 fork 和容器内存不足,再针对真正的进程调整内存。
排查 Maven 构建内存不足
出现 OutOfMemoryError、频繁 Full GC 或容器退出码 137 时,先确认是哪一个进程耗尽内存。
1. 保存失败上下文
mvn -V -e -Dstyle.color=never verify > build.log 2>&1 || true
grep -E 'OutOfMemoryError|Java heap space|Metaspace|Killed|--- .* @ .* ---' build.log | tail -n 402. Maven 主 JVM OOM
项目级可在 .mvn/jvm.config 中配置,例如:
-Xms512m
-Xmx2g
-XX:+HeapDumpOnOutOfMemoryError3. Surefire/Failsafe fork OOM
应调整测试插件的 argLine 和 forkCount,单纯增大 Maven 主 JVM 无效。
4. 只有退出码 137
优先检查容器或主机内存限制。
不要把 -Xmx 设置到接近容器总内存;还要为元空间、线程栈、直接内存和子进程留余量。
从 Reactor 报出的闭环定位模块关系,并通过拆分共享契约消除依赖环。
排查多模块循环依赖
Reactor 在任何编译目标开始前就报告 cyclic reference 时使用。调整 <modules> 顺序不能修复真实依赖环。
1. 获取依赖环
mvn -Dstyle.color=never -e validate > reactor-cycle.log 2>&1 || true
grep -E 'cyclic reference|introduces.*cycle| --> ' reactor-cycle.log预期能看到类似:
<MODULE-A> --> <MODULE-B> --> <MODULE-A>2. 检查形成边的声明
重点检查相关模块的:
<dependencies>- 构建插件及插件依赖
<build><extensions>- 父 POM 和激活 Profile
3. 拆环
最常见做法是把接口、DTO、事件模型或 SPI 下沉到独立 common-api,让原模块都单向依赖它,由更上层模块完成装配。
修复后执行:
mvn clean verify最终应看到可正常排序的 Reactor Build Order 和 BUILD SUCCESS。
统一源码、资源和构建环境编码,解决中文乱码或 unmappable character 编译错误。
修复 Maven 源码编码问题
出现中文注释乱码、资源过滤乱码或 unmappable character for encoding 时使用。
1. 在 POM 中统一编码
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>2. 确认源文件本身是 UTF-8
仅修改 Maven 配置不能修复已经以错误编码保存的源码。用 IDE 或编辑器确认文件编码后再重新保存。
3. 干净构建
mvn clean verify预期结果:
[INFO] BUILD SUCCESS如果只有测试资源或过滤资源乱码,继续检查 maven-resources-plugin、src/test/resources 和运行测试的 JVM 默认编码。不要依赖不同开发机的系统默认编码。