https://maven.apache.org/guides/
https://maven.apache.org/guides/introduction/introduction-to-the-pom.html
https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html
https://maven.apache.org/ref/current/maven-model/maven.html
https://maven.apache.org/settings.html

1. Important Points#

Maven 是 Java 项目的 build / dependency / release 工具:
    pom.xml 描述项目、依赖、插件、构建规则
    lifecycle 定义构建阶段
    plugin 执行具体任务
    repository 存放 dependency 和 artifact

适合:
    Java / Spring Boot 项目
    多模块项目
    企业私服和 CI 发布
    需要统一依赖版本和插件版本的项目

不适合:
    需要高度自定义构建图的复杂 polyglot monorepo
    不愿意遵守固定目录和生命周期约定的项目
mental model:
    source code
        -> pom.xml
        -> Maven lifecycle phase
        -> Maven plugins run goals
        -> dependency resolved from repositories
        -> jar / war / image / published artifact

2. Core Files#

File Purpose
pom.xml 项目构建入口
settings.xml 用户/CI 的仓库、认证、mirror、proxy 配置
.mvn/wrapper/maven-wrapper.properties 固定 Maven Wrapper 版本
.mvn/jvm.config 给 Maven 进程传 JVM 参数
.mvn/maven.config 给 Maven 命令提供默认参数
toolchains.xml 选择编译用的 JDK

3. Handbook Pages#

QuickStart:
    最小项目、Wrapper、test/package

POM / Parent / Profiles:
    pom.xml、继承、profile 激活和 effective POM

Dependency / Plugins / Quality:
    依赖治理、常用 plugin、JaCoCo、SonarQube

Spring Boot / Multi Module:
    starter parent、BOM、多模块 reactor build

Repository / Dockerfile / CI / Release / Security:
    私服、Java 镜像、流水线、发布和供应链安全

Troubleshooting:
    常见问题定位命令和修复方向

4. Standard Layout#

order-api
├── pom.xml
├── .mvn
│   ├── wrapper
│   │   └── maven-wrapper.properties
│   ├── jvm.config
│   └── maven.config
├── src
│   ├── main
│   │   ├── java
│   │   └── resources
│   └── test
│       ├── java
│       └── resources

5. Commands#

./mvnw -v
./mvnw clean test
./mvnw clean package
./mvnw clean verify
./mvnw clean install
./mvnw clean deploy
command rules:
    use ./mvnw in project and CI
    use -B in CI for batch mode
    use clean only when stale output is suspected or release build needs it
    avoid -DskipTests unless the pipeline has another test stage

6. Production Rules#

dependency:
    lock versions in dependencyManagement or BOM
    avoid RELEASE / LATEST / version ranges
    use mvn dependency:tree before overriding transitive dependencies

plugin:
    define plugin versions in pluginManagement
    use maven-enforcer-plugin to enforce Java/Maven/plugin rules
    keep compiler/surefire/failsafe versions explicit

repository:
    do not put secrets in pom.xml
    use settings.xml server id for credentials
    use private proxy repository for enterprise builds

release:
    separate SNAPSHOT and release repositories
    publish from CI with a dedicated deploy identity
    record security overrides and release tags

7. Debug Commands#

./mvnw help:effective-pom
./mvnw help:effective-settings
./mvnw help:active-profiles
./mvnw dependency:tree
./mvnw dependency:tree -Dincludes=org.example:vulnerable-lib
./mvnw help:describe -Dplugin=compiler -Ddetail
./mvnw -X clean test
effective POM:
    当前项目最终生效的 POM，包括 super POM、parent、profile、pluginManagement 合并结果

dependency tree:
    依赖图，用来排查 transitive dependency、版本冲突和漏洞来源
Backward Jenkins QuickStart Forward