Maven Troubleshooting

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
BOM	Bill Of Materials	物料清单；Maven 中用于统一依赖版本
CA	Certificate Authority	证书颁发机构
CI	Continuous Integration	持续集成
JDK	Java Development Kit	Java 开发工具包
PKIX	Public Key Infrastructure using X.509	基于 X.509 的公钥基础设施标准体系
POM	Project Object Model	Maven 项目对象模型
TLS	Transport Layer Security	传输层安全协议
URL	Uniform Resource Locator	统一资源定位符，通常指访问地址

Links#

https://maven.apache.org/guides/
https://maven.apache.org/plugins/maven-help-plugin/
https://maven.apache.org/plugins/maven-dependency-plugin/

1. Debug Commands#

./mvnw -X clean test
./mvnw help:effective-pom
./mvnw help:effective-settings
./mvnw help:active-profiles
./mvnw dependency:tree

2. Parent Not Found#

symptom:
    Non-resolvable parent POM

check:
    parent version
    relativePath
    repository URL
    settings.xml mirror and credentials

3. Dependency Version Is Wrong#

./mvnw dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind
./mvnw help:effective-pom

fix:
    check dependencyManagement
    check imported BOM order
    override vulnerable transitive dependency only after compatibility review

4. Plugin Does Not Run#

插件没有执行时，先确认它是否只在 pluginManagement、是否绑定目标 phase，再看 profile 和 effective POM。

check:
    plugin is under build/plugins, not only pluginManagement
    execution has correct phase
    profile that contains plugin is active

5. Profile Not Active#

./mvnw help:active-profiles
./mvnw -Pprod help:active-profiles

fix:
    pass -Pprofile-id
    check activation conditions
    distinguish Maven profile from Spring profile

6. Tests Are Skipped#

check:
    -DskipTests
    -Dmaven.test.skip=true
    surefire includes/excludes
    test class naming pattern

7. Private Repository 401 / 403#

check:
    server id matches repository id
    CI secret is present
    token permission includes read or deploy
    settings.xml is actually used with -s

8. TLS Error#

symptom:
    PKIX path building failed

fix:
    import company CA into truststore
    pass truststore in MAVEN_OPTS
    do not disable certificate validation

9. Build Is Slow#

check:
    CI cache for ~/.m2/repository
    dependency:go-offline in Docker build
    repeated clean usage
    slow integration tests in local default build

10. Java Version Mismatch#

./mvnw -v
java -version

fix:
    set maven.compiler.release
    use toolchains when build JDK differs from runtime JDK
    enforce version with maven-enforcer-plugin