pom.xml 指南

核心概念

Maven 是什么？

Maven 类似于前端的 npm/yarn/pnpm，是 Java 生态的项目管理和构建工具。

前端工具	Java 工具	作用
`package.json`	`pom.xml`	项目配置文件
`npm install`	`mvn install`	安装依赖
`npm run build`	`mvn package`	构建项目
`node_modules/`	Maven 本地仓库	依赖存储位置
npmjs.com	Maven Central	中央仓库

pom.xml 是什么？

POM = Project Object Model（项目对象模型）

相当于 package.json，定义了项目的：

基本信息（名称、版本、描述）
依赖（类似 dependencies）
构建配置（类似 scripts）
插件配置（类似 webpack/vite 配置）

如何添加依赖

一些专门为 Spring Boot Starter 定制的库，可在 IDEA 的 pom.xml 文件上选择添加启动器。对于其他第三方插件，需手动添加。

Maven 设计理念： pom.xml 是项目的声明式配置文件，需要手动编辑来管理依赖，不能通过命令行安装。

方案一：手动修改 pom.xml

例如添加第三方库：logstash-logback-encoder

访问地址（更常用，可以看到被使用次数）：https://mvnrepository.com/，或访问官方地址：https://central.sonatype.com/
搜索 net.logstash.logback:logstash-logback-encoder
在 pom.xml 中添加配置：

xml

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

安装依赖

方案二：使用 IDEA 来管理依赖

打开 pom.xml → 右键 → Generate（生成）→ Dependency（依赖项）
输入关键词 net.logstash.logback:logstash-logback-encoder 搜索 Maven Central，选择后自动添加到 pom.xml

基础结构

1. XML 声明和 project 根元素

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!-- 项目配置内容 -->
</project>

要点：

modelVersion 固定为 4.0.0（当前 Maven POM 版本）
XML 命名空间声明可以直接复制使用

2. 项目坐标（GAV）

xml

<groupId>com.macro.mall</groupId>
<artifactId>mall</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>

前端类比：

json

{
  "name": "@macro/mall",
  "version": "1.0.0-snapshot"
}

GAV 坐标详解：

元素	说明	前端类比	示例
`groupId`	组织/公司域名	npm scope	`com.macro.mall`
`artifactId`	项目名称	package name	`mall-admin`
`version`	版本号	version	`1.0-SNAPSHOT`
`packaging`	打包方式	-	`jar` / `war` / `pom`

版本号约定：

1.0-SNAPSHOT：开发版本（类似 1.0.0-beta）
1.0.0：正式发布版本

packaging 类型：

jar：Java 应用程序（默认）
war：Web 应用（部署到 Tomcat）
pom：父项目/多模块项目（不生成 jar，仅用于管理）

3. 父项目继承

xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.14</version>
    <relativePath/>
</parent>

前端类比：类似于继承一个基础配置（如 @vue/cli-service 或 CRA 的 react-scripts）

作用：

继承 Spring Boot 的依赖版本管理
继承默认插件配置
继承编译参数和资源处理规则

那么 Maven 怎么知道继承哪一个父 POM、又该去哪里拿？

先分清两件事：GAV 决定"继承谁"，relativePath 只决定"先去哪拿这个文件"。

你写的	决定什么
`groupId` / `artifactId` / `version`	父 POM 是谁。继承关系只看这三个坐标
`<relativePath>`	父 POM 文件先去哪找。找不到就按上面的坐标去仓库取

把父 POM 想成一份公共配置：坐标是它的名字，relativePath 是先翻哪个抽屉——抽屉里没有，就按名字去仓库（Maven Central 或公司私服）取。

relativePath：

指定父 POM 的位置，写不写、怎么写，结果不同：

写法	行为	本机有父 POM 源码吗
省略该标签	默认按 `../pom.xml` 先在本机文件系统找，找不到再走 Maven 仓库	通常有（多模块项目）
空标签 `<relativePath/>`	跳过本机查找，只从 Maven 仓库解析	没有
有值 `<relativePath>../pom.xml</relativePath>`	按该相对路径查找	有，可直接读源码

上面的例子（spring-boot-starter-parent 配空标签）就是第二行的情况：父 POM 是外部 artifact，本机 ../pom.xml 下并没有它。

依赖管理

1. properties（变量定义）

xml

<properties>
    <java.version>17</java.version>
    <mysql-connector.version>9.3.0</mysql-connector.version>
    <hutool.version>5.8.40</hutool.version>
</properties>

前端类比：类似 package.json 中自定义变量或 webpack 的环境变量。

使用变量：

xml

<version>${hutool.version}</version>

内置属性：

${project.version}：当前项目版本
${project.build.finalName}：构建产物名称
${project.basedir}：项目根目录

2. dependencies（直接依赖）

xml

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

前端类比：

json

{
  "dependencies": {
    "vue": "^3.4.0"
  }
}

optional 详解：

xml

<optional>true</optional>

可选依赖，不会传递。

scope 6 种值详解：

Maven 标签	说明	经典场景
`compile`（默认）	编译+运行+打包（全生命周期）	绝大多数依赖。比如 `spring-boot-starter-web`、`spring-boot-starter-data-jpa`、`jjwt-api`。如果不写 scope，默认就是它
`test`	仅测试时使用	单元测试/集成测试。比如 `spring-boot-starter-test`、`junit-jupiter`。这些库只在本地跑 `mvn test` 时用，线上运行时完全不需要
`provided`	编译、测试，但不打包（运行时由外部容器提供）	Servlet API。编译时需要 `HttpServletRequest`、`HttpServletResponse` 等类，但部署到 Tomcat / Jetty 时这些类由容器自带的 `servlet-api.jar` 提供。不需要手动加，因为 `spring-boot-starter-web` 已经帮你处理好了
`runtime`	运行和测试时（编译时不需要）	JDBC 驱动实现。比如 `mysql-connector-j`。你的代码里不会 import 这个驱动的具体类，而是通过 `Class.forName` 或 SPI 机制在运行时动态加载
`system`	同 `provided`，但依赖本地磁盘文件（不在 Maven 仓库中）	几乎不用
`import`	只在 `dependencyManagement` 中使用，不参与打包	BOM（物料清单）。比如在微服务中引入 `spring-cloud-dependencies`，将所有 Spring Cloud 组件的版本号统一管理

依赖版本号：

xml

<!-- 明确指定版本 -->
<version>5.8.40</version>

<!-- 不指定版本（从 parent 或 dependencyManagement 继承） -->
<!-- 省略 <version> 标签 -->

3. dependencyManagement（依赖版本管理）

这是 Maven 的核心特性，前端没有直接对应物！

xml

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.40</version>
        </dependency>
    </dependencies>
</dependencyManagement>

作用：

仅声明版本，不实际引入依赖
子模块可以不写 <version>，自动使用这里定义的版本
统一管理多模块项目的依赖版本

对比示例：

xml

<!-- 父 POM：仅声明版本 -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.40</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 子模块：无需写版本号 -->
<dependencies>
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <!-- 版本自动继承为 5.8.40 -->
    </dependency>
</dependencies>

最佳实践：

父 POM 用 <dependencyManagement> 统一版本
子模块用 <dependencies> 声明实际需要的依赖
避免版本冲突和重复定义

多模块项目

1. 父 POM 配置

xml

<packaging>pom</packaging>

<modules>
    <module>mall-common</module>
    <module>mall-mbg</module>
    <module>mall-admin</module>
</modules>

前端类比：类似 monorepo（pnpm workspace 或 yarn workspace）

json

{
  "workspaces": ["packages/common", "packages/admin", "packages/portal"]
}

项目结构：

mall/
├── pom.xml                 (父 POM, packaging=pom)
├── mall-common/
│   └── pom.xml             (子模块)
├── mall-admin/
│   └── pom.xml             (子模块)
└── mall-portal/
    └── pom.xml             (子模块)

2. 子模块 POM 配置

xml

<parent>
    <groupId>com.macro.mall</groupId>
    <artifactId>mall</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
</parent>

<artifactId>mall-admin</artifactId>

<!-- groupId 和 version 继承自父 POM -->

构建配置

1. build 和 pluginManagement（构建和插件管理）

`<build><plugins>` — 实际执行的插件

xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
        </plugin>
    </plugins>
</build>

maven-compiler-plugin 放在 <plugins> 中：

编译是通用的、必需的操作
所有模块（包括库模块 mall-common、mall-mbg）都需要被编译
所以在父 POM 中强制执行，所有子模块继承这个编译配置

`<build><pluginManagement>` — 仅声明版本，子模块可以继承

xml

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>io.fabric8</groupId>
                <artifactId>docker-maven-plugin</artifactId>
                <version>${docker.maven.plugin.version}</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

spring-boot-maven-plugin 放在 <pluginManagement> 中：

打包成可执行 jar 不是所有模块都需要
mall-common、mall-mbg 是库模块，不需要打包成独立的 jar（只作为依赖被引用）
只有 mall-admin、mall-portal、mall-search 这样的应用模块才需要可执行 jar
所以在父 POM 中仅声明版本，让需要的模块自己选择使用

在这里 spring-boot-maven-plugin 并没有声明版本号，是因为父 POM：

xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.14</version>
</parent>

spring-boot-starter-parent 已经在它的 pluginManagement 中声明了 spring-boot-maven-plugin 的版本，所以在这个项目中继承了这个版本。

2. maven-compiler-plugin 和 spring-boot-maven-plugin

maven-compiler-plugin：

作用：将 Java 源代码编译成字节码（.class 文件）
类似于前端的 Babel — 源代码转译工具
例：javac 命令的包装

spring-boot-maven-plugin：

作用：打包应用、生成可执行 jar、管理依赖
类似于前端的 webpack/Vite — 构建和打包工具
例：mvn package 时的最终产物是可执行 jar

完整的编译打包流程对比：

Java              前端
─────────────────────────────────
源代码            TypeScript/ES6+
  ↓                 ↓
maven-compiler-plugin    Babel/TypeScript
  ↓                 ↓
.class 字节码       JavaScript
  ↓                 ↓
spring-boot-maven-plugin   webpack/Vite
  ↓                 ↓
可执行 jar          bundle.js（可在浏览器运行）

Profiles（环境配置）

什么是 profiles？

<profiles> 允许你定义多组配置，通过激活不同的 profile 来切换构建行为。

前端类比：类似于前端的 .env 文件机制：

前端	Maven	作用
`.env.development`	`<profile><id>dev</id>`	开发环境配置
`.env.production`	`<profile><id>prod</id>`	生产环境配置
`VITE_API_URL=xxx`	`<haborRepository>xxx`	环境变量
`npm run build --mode staging`	`mvn package -P staging`	激活指定环境

基本语法

xml

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <profileActive>dev</profileActive>
            <selfVersion>1.0.40</selfVersion>
            <haborRepository>dockerhubbs.example.com/finchina-dev/${project.artifactId}</haborRepository>
        </properties>
    </profile>
    <profile>
        <id>uat</id>
        <properties>
            <profileActive>uat</profileActive>
            <selfVersion>1.0.40</selfVersion>
            <haborRepository>dockerhubbs.example.com/qyyjt-uat/${project.artifactId}</haborRepository>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <profileActive>prod</profileActive>
            <selfVersion>1.0.40</selfVersion>
            <haborRepository>dockerhubbs.example.com/finchina-prod/${project.artifactId}</haborRepository>
        </properties>
    </profile>
</profiles>

激活方式：

bash

# 激活指定 profile
mvn clean package -P dev
mvn clean package -P uat
mvn clean package -P prod

# 不指定时，activeByDefault=true 的 profile 自动生效（此处为 dev）

<properties> 中定义的变量可在 pom.xml 其他地方通过 ${变量名} 引用：

xml

<!-- 引用 profile 中定义的变量 -->
<version>${selfVersion}</version>
<image>${haborRepository}:${selfVersion}</image>

实战场景：多环境 Docker 镜像构建

以上面的配置为例，同一份代码通过激活不同的 profile，将 Docker 镜像推送到不同的 Harbor 仓库：

                源代码（同一份）
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
  mvn -P dev    mvn -P uat   mvn -P prod
        │            │            │
        ▼            ▼            ▼
 ┌──────────┐  ┌──────────┐  ┌──────────┐
 │   dev    │  │   uat    │  │   prod   │
 │          │  │          │  │          │
 │ version: │  │ version: │  │ version: │
 │ 1.0.40   │  │ 1.0.40   │  │ 1.0.40   │
 │          │  │          │  │          │
 │ 推送到:  │  │ 推送到:  │  │ 推送到:  │
 │finchina- │  │qyyjt-    │  │finchina- │
 │dev/      │  │uat/      │  │prod/     │
 │{artifact}│  │{artifact}│  │{artifact}│
 └──────────┘  └──────────┘  └──────────┘

完整的 CI/CD 流水线（以 dev 环境为例）：

① 代码提交 / 合并到 dev 分支
      │
      ▼
② Jenkins / GitLab CI 触发流水线
      │
      ▼
③ mvn clean package -P dev          ← 激活 dev profile
      │                               读取 profile 中的 properties
      ▼
④ spring-boot-maven-plugin 打出可执行 jar
      │
      ▼
⑤ docker-maven-plugin 构建 Docker 镜像
   镜像标签 = dockerhubbs.example.com/finchina-dev/{artifactId}:1.0.40
      │
      ▼
⑥ docker push → 推送到 Harbor 的 finchina-dev 仓库
      │
      ▼
⑦ Kubernetes / Docker Swarm 从 Harbor 拉取镜像并部署

切换到其他环境只需改变 profile 参数：

bash

# 开发环境 → 推送到 finchina-dev 仓库
mvn clean package -P dev

# 测试环境 → 推送到 qyyjt-uat 仓库
mvn clean package -P uat

# 生产环境 → 推送到 finchina-prod 仓库
mvn clean package -P prod

activation（激活条件）

除了手动 mvn -P 指定，profile 还支持自动激活：

xml

<profile>
    <id>dev</id>
    <activation>
        <!-- 方式 1：默认激活（不指定 -P 时生效） -->
        <activeByDefault>true</activeByDefault>

        <!-- 方式 2：JDK 版本匹配时激活 -->
        <jdk>[17,)</jdk>

        <!-- 方式 3：操作系统匹配时激活 -->
        <os>
            <name>Windows</name>
            <family>windows</family>
        </os>

        <!-- 方式 4：系统属性存在/匹配时激活 -->
        <property>
            <name>env</name>
            <value>dev</value>
        </property>

        <!-- 方式 5：文件存在时激活 -->
        <file>
            <exists>src/main/resources/application-dev.yml</exists>
        </file>
    </activation>
</profile>

激活方式	说明	典型场景
`activeByDefault`	未指定 `-P` 时默认生效	dev 环境作为本地开发默认配置
`jdk`	JDK 版本匹配时激活	JDK 17+ 使用新依赖，JDK 8 兼容
`os`	操作系统匹配时激活	Windows/Linux 使用不同本地路径
`property`	`-D` 传入的属性匹配时激活	`mvn -Denv=prod` 激活 prod
`file`	指定文件存在时激活	检测到配置文件自动切换环境

Maven profiles vs Spring Boot profiles

这是一个容易混淆的概念，两者同名但完全不同：

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Maven profiles                    Spring Boot profiles          │
│  ──────────────                    ────────────────────          │
│                                                                 │
│  作用于：构建时                     作用于：运行时                │
│  配置位置：pom.xml                  配置位置：application-{x}.yml│
│  激活方式：mvn -P dev              激活方式：                    │
│            java -jar app.jar --spring.profiles.active=prod      │
│  决定什么：                       决定什么：                     │
│    构建产物形态                      数据库连接串                 │
│    依赖集合                          日志级别                     │
│    插件行为                          第三方服务地址               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

对比维度	Maven profiles	Spring Boot profiles
生效时机	构建时（`mvn` 命令执行期间）	运行时（`java -jar` 启动期间）
配置文件	`pom.xml`	`application-dev.yml` / `application-prod.yml`
激活命令	`mvn package -P dev`	`java -jar app.jar --spring.profiles.active=prod`
决定什么	构建产物形态、依赖集合、插件行为	数据库连接串、日志级别、第三方服务地址
前端类比	`npm run build --mode production`	`process.env.NODE_ENV` 运行时读取
产物是否绑定环境	是（不同 profile 打出不同的包）	否（同一个包，启动时决定行为）

现代 Spring Boot 项目的推荐做法：

┌─────────────────────────────────────────────────────────────────┐
│                    环境配置职责分离                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  pom.xml（Maven profiles）         只管「构建」                  │
│  ┌──────────────────────────────┐                               │
│  │ • Docker 镜像推送地址         │                               │
│  │ • 不同 JDK 版本的依赖适配     │  ← 构建时决定                │
│  │ • CI/CD 构建变体              │                               │
│  │ • 是否启用代码混淆/加固       │                               │
│  └──────────────────────────────┘                               │
│                                                                 │
│  application-{env}.yml（Spring Boot profiles）  只管「运行」     │
│  ┌──────────────────────────────┐                               │
│  │ • 数据库连接串                │                               │
│  │ • Redis 地址                  │  ← 运行时决定                │
│  │ • 日志级别                    │                               │
│  │ • 第三方 API 地址             │                               │
│  └──────────────────────────────┘                               │
│                                                                 │
│  优势：打出一个通用的 jar，部署到任何环境都能通过启动参数切换配置  │
│  java -jar app.jar --spring.profiles.active=prod                │
│  java -jar app.jar --spring.profiles.active=uat                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

替代方案

Maven profiles 不是唯一的选择，根据场景可以选用更合适的方式：

方案	做法	优点	缺点	适合场景
Maven profiles	`pom.xml` 中定义多组配置，`mvn -P` 激活	集中可读、语义明确	配置提交到代码库	环境固定、团队协作
命令行 `-D`	`mvn package -Denv=dev -Dregistry=xxx`	灵活、无需改 pom.xml	参数多时命令冗长	临时构建、实验
CI/CD 平台变量	GitLab CI / Jenkins 中配置环境变量	敏感信息安全加密	本地开发无法复用	纯 CI/CD 场景
Shell 脚本封装	`build.sh` 中 `case $ENV` 映射不同配置	逻辑集中、可复用	多一层抽象	构建流程复杂时

选择建议： 环境少且固定（如 dev/uat/prod）→ profiles；环境多且经常变动 → CI 平台变量；只是临时测试 → 命令行 -D；涉及密码、密钥等敏感信息 → CI 平台变量（profiles 会提交到代码库）。

仓库配置

repositories（依赖仓库）

下载项目使用的依赖库（jar 文件）
例如：spring-boot-starter-web、hutool-all、mysql-connector-j、lombok
这些库最终会被打包进 jar 中或在运行时使用，类似于前端 axios 等第三方库会被打包进 bundle.js

xml

<repositories>
    <repository>
        <id>aliyunmaven</id>
        <name>aliyun</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </repository>
    <repository>
        <id>central2</id>
        <name>central2</name>
        <url>https://repo1.maven.org/maven2/</url>
    </repository>
</repositories>

先从阿里云镜像中查找，如果没有找到，再从官方的 Maven 中央仓库查找。

pluginRepositories（插件仓库）

下载 Maven 构建插件本身
例如：maven-compiler-plugin、spring-boot-maven-plugin、docker-maven-plugin
这些是构建工具，不是项目的运行依赖，类似于前端的 webpack、Vite 等不会被打包的第三方库

xml

<pluginRepositories>
    <pluginRepository>
        <id>aliyunmaven</id>
        <name>aliyun</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </pluginRepository>
    <pluginRepository>
        <id>central2</id>
        <name>central2</name>
        <url>https://repo1.maven.org/maven2/</url>
    </pluginRepository>
</pluginRepositories>

先从阿里云镜像中查找，如果没有找到，再从官方的 Maven 中央仓库查找。

Maven 阶段

命令	作用
`clean`	清理 `target` 编译目录
`validate`	验证项目结构和 pom.xml 是否正确
`compile`	编译源代码
`test`	运行测试
`package`	打包生成 jar/war
`verify`	对集成测试结果做检查
`install`	将 jar 复制到本地 Maven 仓库，给其他项目引用
`site`	生成项目站点文档和报告
`deploy`	部署到远程仓库

构建失败诊断

本章范围： 不提供 mvn 命令速查——dependency:tree 的参数组合、-X 输出该看哪几行，这类查表交给 AI Agent 或官方文档更快，也不容易过期。本章只写 AI 补不上的两件事：
私有构建环境上下文：私有父 POM、内网私服、编译用 JDK 只存在于你的机器和内网，Agent 看不到，只能由人确认。
归因路径与修复方案审查：判断 Agent 给出的修复该不该采纳、改完之后验证什么。

1. 私有构建环境上下文清单

同一个 pom.xml，你的机器能构建、同事的机器失败，差别几乎都在这五处——它们不在代码库里：

配置来源	实际位置	进 Git	Agent 可见
私有父 POM	私服上的内部 artifact	否	否（只看到 `<parent>` 坐标）
私服地址与镜像	`~/.m2/settings.xml`、`$MAVEN_HOME/conf/settings.xml`	否	否
私服认证	`settings.xml` 的 `<servers>`	否，也不该	否
本地仓库缓存	`~/.m2/repository`（可被 `localRepository` 覆盖）	否	否
编译用 JDK	`JAVA_HOME`、`~/.m2/toolchains.xml`	否	只能看到配置，看不到环境

1.1 私有父 POM

<parent> 指向内部 artifact 时，你对版本和插件的认知主要来自一个没有源码的 POM。

位置线索：<relativePath/> 是空标签时，父 POM 只从 Maven 仓库解析，本机没有它的源码，只能靠 effective-pom 反推；省略标签或写成 ../pom.xml 时，父 POM 就在项目目录里，可以直接读源码。三种写法的完整对照见《基础结构 → 3. 父项目继承》。
拿法：按 GAV 从私服下载 .pom；拿不到就问负责发版的人，不要猜内容。
拿不到也能确认版本：effective-pom 已经把父 POM 展开合并（见第 3 节），版本号和插件配置都能读到，不必依赖父 POM 原文。

Agent 最常犯的错误是"猜父 POM 里有什么"。猜测往往语法通顺，但版本号在私服上并不存在。凡涉及"父 POM 定义了 X"的结论，都要用 effective-pom 验证一次。

1.2 私服与 mirror

settings.xml 有两个位置，用户级优先（同名配置由用户级覆盖全局级）。<mirrors> 会劫持仓库请求：

`mirrorOf` 写法	效果
`central`	只劫持中央仓库
`*`	劫持全部仓库，包括 `pom.xml` 里 `<repositories>` 声明的私服
`external:*`	劫持除 localhost 和文件协议外的全部

mirrorOf=* 是"依赖明明在私服上却 404"的头号原因：请求被转给了镜像，而镜像里没有内部制品。排查顺序固定为——请求最终落到哪个地址 → 那个地址上到底有没有这个 artifact。

1.3 SNAPSHOT 策略

1.0-SNAPSHOT 的产物每次发布都可能变，Maven 允许缓存，默认每天检查一次更新。

症状：昨天能编译，今天报找不到符号/方法，而你自己一行没改。
原因：私服上的 SNAPSHOT 被重新 deploy，方法签名变了。
判断：本地仓库里的 SNAPSHOT 文件名带时间戳（xxx-1.0-SNAPSHOT-20260101.120000-1.jar），比对它的下载时间与私服 maven-metadata.xml 的更新时间。
处理：强制刷新本地缓存后重新构建；仍不一致时先怀疑"拿到的不是最新 SNAPSHOT"，而不是代码。

1.4 Toolchains（编译用的不是你以为的那个 JDK）

三个 JDK 要分开看，出问题时逐个对：

角色	由谁决定	出错时的表现
运行 Maven 的 JDK	`JAVA_HOME`	插件加载失败、连私服握手/TLS 报错
编译目标版本	`maven.compiler.release`（或 `source`+`target`）、toolchain	字节码版本不匹配
IDE 编译用的 JDK	IDEA 的 Project SDK	IDE 能跑，命令行编不过（或反之）

"IDEA 里能跑、mvn 报错"几乎总是上表里有两行指向不同 JDK。 判断方法：看 effective-pom 中 maven-compiler-plugin 的 release/source/target 实际值，再和 JAVA_HOME 对一遍。

~/.m2/toolchains.xml 用于让 Maven 忽略 JAVA_HOME、按配置挑 JDK，多见于同时维护 JDK 8 和 JDK 21 的项目。

2. 四类报错的归因路径

排查第一步不是读报错内容，而是确定失败发生在哪个阶段——对照上文《Maven 阶段》：validate/compile 失败是依赖解析或配置问题，test 失败是代码或环境问题，package/deploy 失败是插件或私服问题。阶段定错，后面的分析全错。

报错类型	首次出现阶段	大概率归属	第一个要看的证据
编译期找不到符号	`compile`	依赖缺失 / 版本太旧	effective-pom 里该 artifact 的版本
`NoClassDefFoundError` / `NoSuchMethodError`	运行期（`test` 或启动后）	运行期 classpath 与编译期不一致	产物中的 jar 清单及各自版本
版本仲裁偏离预期	任意阶段	依赖传递 / 仲裁规则	该 artifact 在依赖树中的全部出现位置
插件与 JDK 不匹配	`compile` / `test` / `package`	插件版本 / 字节码版本	插件版本及其支持的最低 JDK

2.1 编译期找不到符号（cannot find symbol）

先区分是"类不存在"还是"方法/字段不存在"：

整个类找不到：依赖没声明、scope 不对（test、provided 不进主代码 classpath）、或被 optional 截断。
类在但方法找不到：classpath 上该类的版本比代码里用的 API 旧，编译期解析到了另一个版本。
只在 IDE 里报错：索引与 pom 不一致。以命令行的结论为准，先同步项目再重试。

2.2 运行期 NoClassDefFoundError / NoSuchMethodError

本质是编译期和运行期看到的 classpath 不是同一份。

错误	含义	高频原因
`NoClassDefFoundError: A`	运行期加载不到 A	A 的 scope 是 `provided` 而容器里没有；A 被 `optional` 截断；打包漏了 A
`NoSuchMethodError: A.m()`	加载到了 A 的旧版本	仲裁选了旧版本；容器或父 ClassLoader 提供了旧 jar
`ExceptionInInitializerError` 后紧跟 `NoClassDefFoundError: Could not initialize class A`	静态初始化失败	第一次失败的根因在别处，第二次只是"初始化不完整"的残留

最后一行最容易误判：第二个 NoClassDefFoundError 不是新问题，必须回去看第一个 ExceptionInInitializerError 及其 Caused by。

2.3 版本仲裁偏离预期

Maven 的规则是 nearest wins（最近者胜），不是"取最高版本"（这点与 Gradle 不同）：

依赖树中路径最短的版本胜出；路径长度相同时，先声明的胜出。
所以"pom.xml 里写的 3.x 没生效、实际用的是 2.x"完全可能：另一条更短的路径先到达。

判断方法：在依赖树中列出该 artifact 的全部出现位置，找最短的那条路径是从哪个依赖进来的。只有一条路径时，才去查 BOM / dependencyManagement 的覆盖是否生效。

2.4 插件与 JDK 不匹配

Unsupported class file major version 65：一方用 JDK 21 编译，产物被更老的工具读取——两端 JDK 不一致。
测试插件版本过旧：不认识 JUnit 5，测试不执行或报 No tests found。
Boot 插件与 Boot 版本不匹配：打出的 jar 缺少启动类清单或依赖目录。
Maven 自身版本过低：插件要求更高的 Maven 主版本。

这类问题的判断依据是插件版本，不是报错文案；版本号在 effective-pom 的 build.plugins 里。

3. effective-pom 该看哪几段

mvn help:effective-pom 输出的是合并完成的最终 POM：父 POM、dependencyManagement、激活的 profile、插件默认配置全部展开。它通常几千行，不要通读，只取四段：

段落	回答什么问题	判读要点
`dependencyManagement`	这个版本号是谁定的	区分"本文件写的"与"继承来的"，后者要继续往上追
`dependencies`	实际解析到的直接依赖	`<version>` 都应有具体值；残留 `${...}` 说明变量没解析
`build.plugins`	插件的实际版本与配置	只写进 `pluginManagement` 不生效，必须出现在 `plugins` 里
`repositories` + 激活的 `profiles`	从哪个地址下载	要配合 `settings.xml` 的 mirror，才能确定请求最终落到哪

两种用法：

定位：报错涉及哪个 artifact 或插件，就搜它的 GAV，只读那一段。
比对：改动前后各导出一次做文本 diff。**"改了却没变化"**是最常见的事故——说明改的位置不生效（改了 pluginManagement 但模块没引用，或改的 profile 没被激活）。

4. 冲突处理决策表与 AI 修复方案审查清单

4.1 决策表

先确认现象，再选手段；最右一列的"主要风险"决定了改完要验证什么。

现象	可选手段	适用	主要风险
传递依赖版本不符预期	在 `<dependencyManagement>` 锁定版本	首选，改动集中	可能与其他库不兼容
需要彻底断开某条传递	`<exclusions>`	确实完全不需要该依赖	掩盖问题，代码可能间接依赖它
多个库共享一套版本	引入 BOM（`scope=import`）	生态内成套组件	BOM 互相覆盖，导入顺序敏感
编译期有、运行期没有	调整 `scope`	`provided` 误用	改成 `compile` 会与容器自带 jar 冲突
插件版本不对	`build/pluginManagement` 锁版本	首选	只在模块实际引用 `plugins` 时生效

给出结论时必须说明两件事：为什么选这个手段、被排除或被锁定的依赖还有谁在用。只写"加了 exclusion 就好了"，等于把问题推迟到运行时。

4.2 AI 修复方案审查清单

Agent 的建议在语法上通常都成立，问题在于它不知道你的私服、父 POM 和兼容性约束。采纳前逐条核对：

检查项	危险信号	正确做法
版本号来源	给出一个"看起来合理"的版本	先去私服确认该版本存在
改动位置	直接改根 POM 或父 POM	确认能否动父 POM（影响所有模块）
手段选择	用 `exclusion` 掩盖版本冲突	优先统一版本，排除是最后手段
scope 调整	把 `provided` 改成 `compile`	先确认容器是否已提供同名类
SNAPSHOT	靠依赖 SNAPSHOT 解决问题	SNAPSHOT 会变，不能作为稳定依赖
升级范围	顺手升级 Boot / Spring 小版本	跨版本升级是独立任务，不混在排障里
验证方式	只说"应该可以了"	要求给出改动前后的 effective-pom 差异

改完必做三件事：clean 后重新构建（排除 target 里的旧产物）、比对 effective-pom、确认私服上目标版本确实可下载。

pom.xml 指南 ​

核心概念 ​

Maven 是什么？ ​

pom.xml 是什么？ ​

如何添加依赖 ​

方案一：手动修改 pom.xml ​

方案二：使用 IDEA 来管理依赖 ​

基础结构 ​

1. XML 声明和 project 根元素 ​

2. 项目坐标（GAV） ​

3. 父项目继承 ​

依赖管理 ​

1. properties（变量定义） ​

2. dependencies（直接依赖） ​

3. dependencyManagement（依赖版本管理） ​

多模块项目 ​

1. 父 POM 配置 ​

2. 子模块 POM 配置 ​

构建配置 ​

1. build 和 pluginManagement（构建和插件管理） ​

<build><plugins> — 实际执行的插件 ​

<build><pluginManagement> — 仅声明版本，子模块可以继承 ​

2. maven-compiler-plugin 和 spring-boot-maven-plugin ​

Profiles（环境配置） ​

什么是 profiles？ ​

基本语法 ​

实战场景：多环境 Docker 镜像构建 ​

activation（激活条件） ​

Maven profiles vs Spring Boot profiles ​

替代方案 ​

仓库配置 ​

repositories（依赖仓库） ​

pluginRepositories（插件仓库） ​

Maven 阶段 ​

构建失败诊断 ​

1. 私有构建环境上下文清单 ​

1.1 私有父 POM ​

1.2 私服与 mirror ​

1.3 SNAPSHOT 策略 ​

1.4 Toolchains（编译用的不是你以为的那个 JDK） ​

2. 四类报错的归因路径 ​

2.1 编译期找不到符号（cannot find symbol） ​

2.2 运行期 NoClassDefFoundError / NoSuchMethodError ​

2.3 版本仲裁偏离预期 ​

2.4 插件与 JDK 不匹配 ​

3. effective-pom 该看哪几段 ​

4. 冲突处理决策表与 AI 修复方案审查清单 ​

4.1 决策表 ​

4.2 AI 修复方案审查清单 ​

pom.xml 指南

核心概念

Maven 是什么？

pom.xml 是什么？

如何添加依赖

方案一：手动修改 pom.xml

方案二：使用 IDEA 来管理依赖

基础结构

1. XML 声明和 project 根元素

2. 项目坐标（GAV）

3. 父项目继承

依赖管理

1. properties（变量定义）

2. dependencies（直接依赖）

3. dependencyManagement（依赖版本管理）

多模块项目

1. 父 POM 配置

2. 子模块 POM 配置

构建配置

1. build 和 pluginManagement（构建和插件管理）

`<build><plugins>` — 实际执行的插件

`<build><pluginManagement>` — 仅声明版本，子模块可以继承

2. maven-compiler-plugin 和 spring-boot-maven-plugin

Profiles（环境配置）

什么是 profiles？

基本语法

实战场景：多环境 Docker 镜像构建

activation（激活条件）

Maven profiles vs Spring Boot profiles

替代方案

仓库配置

repositories（依赖仓库）

pluginRepositories（插件仓库）

Maven 阶段

构建失败诊断

1. 私有构建环境上下文清单

1.1 私有父 POM

1.2 私服与 mirror

1.3 SNAPSHOT 策略

1.4 Toolchains（编译用的不是你以为的那个 JDK）

2. 四类报错的归因路径

2.1 编译期找不到符号（cannot find symbol）

2.2 运行期 NoClassDefFoundError / NoSuchMethodError

2.3 版本仲裁偏离预期

2.4 插件与 JDK 不匹配

3. effective-pom 该看哪几段

4. 冲突处理决策表与 AI 修复方案审查清单

4.1 决策表

4.2 AI 修复方案审查清单