Maven 下载与配置完全指南

Maven 是 Java 开发的核心构建工具，安装前需要先确保系统已安装 JDK 8 及以上版本 ，可通过命令行执行 java -version 确认。Maven 本身没有安装程序，下载压缩包解压后配置环境变量即可使用。

一、下载 Maven

官方下载地址 ：https://maven.apache.org/download.cgi

这是 Apache Maven 项目唯一指定的下载入口，页面会自动显示当前最新稳定版。截至 2026 年 5 月， 最新稳定版本为 3.9.16 ，另有预览版 4.0.0-rc-6。

下载时注意：

Windows 用户选择 apache-maven-3.9.x-bin.zip
Linux/macOS 用户选择 apache-maven-3.9.x-bin.tar.gz

⚠️ 务必下载 bin 包，不要下载 src 源码包。

下载后解压到合适位置， 路径不要包含中文和空格 ，例如 D:\dev\maven\apache-maven-3.9.16。

二、配置环境变量

Windows

新建系统变量 MAVEN_HOME
右键「此电脑」→「属性」→「高级系统设置」→「环境变量」→ 在「系统变量」中点击「新建」：
- 变量名：MAVEN_HOME
- 变量值：Maven 解压目录，如 D:\dev\maven\apache-maven-3.9.16
编辑 Path 变量
在「系统变量」中找到 Path，点击「编辑」→「新建」，输入 %MAVEN_HOME%\bin，然后一路确定保存。

三、验证安装

打开新的命令行窗口，执行：

bash

mvn -v

看到类似输出即表示配置成功：

text

1
2
3

Apache Maven 3.9.16
Maven home: D:\dev\maven\apache-maven-3.9.16
Java version: 21, vendor: Oracle Corporation

四、配置阿里云镜像（必做）

Maven 默认从国外中央仓库下载依赖，国内网络下载极慢甚至频繁失败，强烈建议配置国内镜像。

找到 Maven 目录下的 conf/settings.xml，在 <mirrors> 标签内添加：

xml

<mirror>
    <id>aliyunmaven</id>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
</mirror>

保存即可。<mirrorOf>central</mirrorOf> 表示用阿里云镜像替代 Maven 中央仓库。

五、配置本地仓库（建议做）

Maven 默认将依赖下载到 ~/.m2/repository，时间长了会占用 C 盘大量空间，建议改到非系统盘。

在 settings.xml 中找到 <localRepository> 标签（通常在注释中），取消注释并修改为：

xml

1	<localRepository>D:\dev\maven\repo</localRepository>

路径可自行指定，目录不存在会自动创建。

六、在 IDEA 中集成

打开 IDEA → File → Settings（快捷键 Ctrl+Alt+S）→ 搜索 Maven ：

Maven home path ：选择解压的 Maven 目录
User settings file ：选择修改过的 settings.xml
Local repository ：通常会自动识别为你在 settings.xml 中配置的路径

点击 Apply → OK 即可。

七、settings.xml 完整结构与常用标签

settings.xml 是 Maven 的全局配置文件，管的是「从哪下、下到哪、用什么账号」，与具体项目无关。

文件位置（两个位置都可放，用户级优先级更高）：

级别	路径	说明
全局	`${MAVEN_HOME}/conf/settings.xml`	影响本机所有用户
用户	`~/.m2/settings.xml`（Windows：`C:\Users\用户名\.m2\settings.xml`）	只影响当前用户，推荐

💡 建议改用户级 ~/.m2/settings.xml，这样以后升级 Maven 换目录时配置不会丢。

完整示例（可直接替换）

xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <!-- 1. 本地仓库位置 -->
  <localRepository>D:\dev\maven\repo</localRepository>

  <!-- 2. 是否让 Maven 与用户交互（一般 false，让 CI 自动跑） -->
  <interactiveMode>false</interactiveMode>

  <!-- 3. 离线模式：true 时只读本地仓库，不去远程下 -->
  <offline>false</offline>

  <!-- 4. 镜像：把中央仓库换成国内源 -->
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

  <!-- 5. 私服账号密码（需要认证的仓库才配） -->
  <servers>
    <server>
      <id>nexus-releases</id>
      <username>deploy</username>
      <password>your-password</password>
    </server>
  </servers>

  <!-- 6. 代理（公司内网需走代理时配） -->
  <proxies>
    <proxy>
      <id>company-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
      <nonProxyHosts>localhost|127.0.0.1</nonProxyHosts>
    </proxy>
  </proxies>

  <!-- 7. 全局 JDK / 编码等参数 -->
  <profiles>
    <profile>
      <id>jdk-8</id>
      <activation>
        <activeByDefault>true</activeByDefault>
        <jdk>1.8</jdk>
      </activation>
      <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
        <maven.compiler.compilerVersion>8</maven.compiler.compilerVersion>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      </properties>
    </profile>
  </profiles>

</settings>

settings.xml 标签速查

标签	作用	常用值 / 说明
`<localRepository>`	本地仓库目录	如 `D:\dev\maven\repo`；不配默认 `~/.m2/repository`
`<interactiveMode>`	是否允许交互输入	`true` / `false`
`<offline>`	离线模式	`true` 时只用本地已有依赖（断网/省流量）
`<mirrors>`	镜像配置（最重要）	里面放 `<mirror>`，可配多个
`<mirror><id>`	镜像唯一标识	自定义，如 `aliyunmaven`
`<mirror><url>`	镜像仓库地址	见「九、仓库地址大全」
`<mirror><mirrorOf>`	拦截哪些仓库	`central`、`*`、`!私服id` 等，见下表
`<servers>`	私服认证账号	`<id>` 必须与 pom 里 repository 的 id 一致
`<proxies>`	网络代理	内网环境用
`<profiles>`	环境参数集合	可配 JDK、编码、仓库等
`<activeProfiles>`	显式激活 profile	如 `<activeProfile>jdk-8</activeProfile>`
`<pluginGroups>`	插件组（可省略 groupId 调插件）	一般不用改

`<mirrorOf>` 常用写法（易踩坑）

写法	含义
`central`	只代理中央仓库（最常用）
`*`	代理所有仓库（⚠️ 会连私服也代理掉，私服会失效）
`external:*`	代理所有非 localhost / 非文件的仓库
`*,!nexus-releases`	代理所有，但排除私服 id（推荐用法）
`repo1,repo2`	只代理指定 id 的仓库

⚠️ 如果把 <mirrorOf> 写成 *，而公司私服也在 pom 里配置了，那么私服请求会被镜像劫持，导致「下载不到内部包」。此时必须用 *,!私服id 排除。

八、pom.xml 核心标签详解

pom.xml 是项目级配置，管的是「这个项目叫什么、依赖谁、怎么打包」。一个最小可用的 pom：

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
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <!-- 1. POM 模型版本，固定 4.0.0 -->
  <modelVersion>4.0.0</modelVersion>

  <!-- 2. 继承父工程（可选，Spring Boot 项目通常继承 starter-parent） -->
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version>
    <relativePath/> <!-- 空表示从仓库找，不从上级目录找 -->
  </parent>

  <!-- 3. 项目坐标（三要素，全局唯一） -->
  <groupId>com.example</groupId>
  <artifactId>demo-service</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>jar</packaging> <!-- jar / war / pom -->

  <!-- 4. 项目名与描述 -->
  <name>demo-service</name>
  <description>示例服务</description>

  <!-- 5. 统一版本变量，便于集中管理 -->
  <properties>
    <java.version>8</java.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <fastjson.version>2.0.32</fastjson.version>
  </properties>

  <!-- 6. 依赖版本统一声明（子模块引依赖时不用写版本） -->
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.alibaba.fastjson2</groupId>
        <artifactId>fastjson2</artifactId>
        <version>${fastjson.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <!-- 7. 实际依赖 -->
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>com.alibaba.fastjson2</groupId>
      <artifactId>fastjson2</artifactId>
    </dependency>
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <scope>provided</scope> <!-- 只编译期用，不打进包 -->
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <!-- 8. 构建配置 -->
  <build>
    <finalName>demo</finalName>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

  <!-- 9. 额外仓库（私服 / 特殊仓库） -->
  <repositories>
    <repository>
      <id>nexus-releases</id>
      <url>http://nexus.company.com/repository/maven-releases/</url>
      <releases><enabled>true</enabled></releases>
      <snapshots><enabled>false</enabled></snapshots>
    </repository>
  </repositories>

</project>

pom.xml 标签速查

标签	作用	说明
`<modelVersion>`	POM 版本	固定 `4.0.0`
`<parent>`	继承父工程	继承依赖版本、插件配置
`<groupId>`	组织/公司标识	如 `com.tencent.oa`
`<artifactId>`	项目/模块名	如 `tencent-rpt-server`
`<version>`	版本号	`SNAPSHOT` 为快照版（可覆盖），不带为正式版
`<packaging>`	打包类型	`jar`（默认）/ `war` / `pom`（父工程）
`<properties>`	变量定义	用 `${xxx}` 引用，集中管版本
`<dependencyManagement>`	依赖版本管理	只声明版本不引入；子模块引时不写版本
`<dependencies>`	项目依赖	真正的依赖列表
`<scope>`	依赖作用域	见「十、依赖作用域」
`<optional>`	可选依赖	`true` 时不传递给下游项目
`<exclusions>`	排除传递依赖	解决冲突/去冗余
`<build>`	构建配置	内含 `<plugins>`、`<resources>` 等
`<finalName>`	产物名	打成 `demo.jar`
`<plugins>`	构建插件	如 `spring-boot-maven-plugin`
`<repositories>`	依赖下载仓库	私服/第三方仓库
`<distributionManagement>`	发布目标仓库	`deploy` 时推到哪
`<profiles>`	环境配置	多环境（dev/test/prod）打包
`<modules>`	子模块列表	父工程用，见「十三、多模块工程」

`<distributionManagement>`（发布用）

xml

<distributionManagement>
  <repository>
    <id>nexus-releases</id>   <!-- 必须与 settings.xml 里 server 的 id 一致 -->
    <url>http://nexus.company.com/repository/maven-releases/</url>
  </repository>
  <snapshotRepository>
    <id>nexus-snapshots</id>
    <url>http://nexus.company.com/repository/maven-snapshots/</url>
  </snapshotRepository>
</distributionManagement>

⚠️ 发布失败最常见原因：settings.xml 里 <server><id> 与这里 <repository><id> 不一致，导致密码匹配不上。

九、仓库地址大全

官方中央仓库

名称	地址
Maven Central（官方）	`https://repo.maven.apache.org/maven2/`
Maven Central（备用）	`https://repo1.maven.org/maven2/`

阿里云镜像（推荐）

仓库	地址	说明
public（聚合）	`https://maven.aliyun.com/repository/public`	推荐，含 central + jcenter
central	`https://maven.aliyun.com/repository/central`	只代理中央仓库
jcenter	`https://maven.aliyun.com/repository/jcenter`	jcenter 代理
google	`https://maven.aliyun.com/repository/google`	Android / Google 组件
gradle-plugin	`https://maven.aliyun.com/repository/gradle-plugin`	Gradle 插件
spring	`https://maven.aliyun.com/repository/spring`	Spring 相关
spring-plugin	`https://maven.aliyun.com/repository/spring-plugin`	Spring 插件
releases	`https://maven.aliyun.com/repository/releases`	正式版私服代理
snapshots	`https://maven.aliyun.com/repository/snapshots`	快照版私服代理

其它国内镜像

名称	地址
华为云	`https://repo.huaweicloud.com/repository/maven/`
腾讯云	`https://mirrors.cloud.tencent.com/nexus/repository/maven-public/`
网易	`https://mirrors.163.com/maven/repository/maven-public/`

镜像 vs 仓库：配置位置不同

方式	配置位置	特点
镜像 `<mirror>`	`settings.xml`	全局生效，拦截（替换）指定仓库；常规加速首选
仓库 `<repository>`	`pom.xml` 或 settings 的 profile	只对当前项目生效，作为额外下载源

镜像配置示例（settings.xml，多镜像写法）：

xml

<mirrors>
  <!-- 阿里云聚合源，覆盖中央仓库 -->
  <mirror>
    <id>aliyunmaven</id>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
  <!-- 指定仓库走阿里云 spring 源 -->
  <mirror>
    <id>aliyun-spring</id>
    <name>阿里云 Spring 仓库</name>
    <url>https://maven.aliyun.com/repository/spring</url>
    <mirrorOf>spring-milestones,spring-snapshots</mirrorOf>
  </mirror>
</mirrors>

查看仓库所有包的地址（在线浏览 / 搜索）

想找一个包的最新版本、所有历史版本、groupId / artifactId 全称时，用下面这些地址直接在浏览器里查。

1. 在线搜索平台（最常用）

平台	地址	特点
Maven Repository（推荐）	https://mvnrepository.com/	最好用，可看版本列表、依赖关系、被谁引用、复制坐标
Maven Central 官方搜索	https://central.sonatype.com/	官方新站，覆盖最全，支持全文搜索
Maven Central（旧版）	https://search.maven.org/	旧版界面，仍可用
Sonatype OSS Index	https://ossindex.sonatype.org/	查安全漏洞（CVE）常用
MVNRepository 依赖排行	https://mvnrepository.com/popular	看热门包排行

💡 复制坐标时注意：网页上的 <dependency> 片段可能引用的是老版本，粘到 pom 前先核对版本号。

2. 直接浏览仓库目录（看「所有包」）

任何一个 Maven 仓库都能当目录网站打开，路径规则是：

1	仓库根地址 / groupId 的点换斜杠 / artifactId / version /

仓库	浏览地址	说明
Maven Central	`https://repo.maven.apache.org/maven2/`	官方中央仓库根，可逐级点进去
阿里云 public	`https://maven.aliyun.com/repository/public/`	阿里云聚合仓库，可直接浏览
阿里云 central	`https://maven.aliyun.com/repository/central/`	只含中央仓库内容
阿里云 spring	`https://maven.aliyun.com/repository/spring/`	Spring 相关包
华为云	`https://repo.huaweicloud.com/repository/maven/`	可浏览目录
腾讯云	`https://mirrors.cloud.tencent.com/nexus/repository/maven-public/`	可浏览目录
网易	`https://mirrors.163.com/maven/repository/maven-public/`	可浏览目录

实例：找 fastjson2 的所有版本

1. 打开 https://repo.maven.apache.org/maven2/
2. 依次点进：com/ → alibaba/ → fastjson2/
3. 看到 fastjson2/ 下按版本号排列的目录（2.0.0、2.0.1 ... 2.0.53）
4. 点进某个版本，能看到 fastjson2-2.0.53.jar、.pom、.jar.sha1 等文件

对应的直链就是：

1 2	https://repo.maven.apache.org/maven2/com/alibaba/fastjson2/ https://repo.maven.apache.org/maven2/com/alibaba/fastjson2/2.0.53/

实例：找 Spring Boot 所有版本

1	https://repo.maven.apache.org/maven2/org/springframework/boot/spring-boot-starter-parent/

3. 私服（Nexus / Artifactory）浏览地址

公司私服同样能浏览全部内部包，地址通常是 Nexus 的仓库根路径：

类型	浏览地址格式	示例
Nexus 2	`http://主机:8081/nexus/content/repositories/仓库名/`	`.../repositories/maven-releases/`
Nexus 3	`http://主机:8081/repository/仓库名/`	`.../repository/maven-releases/`
Nexus 3 搜索页	`http://主机:8081/#browse/browse`	图形化搜索全部组件
Artifactory	`http://主机:8081/artifactory/仓库名/`	—
Artifactory UI	`http://主机/artifactory/webapp/#/artifacts`	图形化浏览

⚠️ 私服一般需要登录，直接开链接会 401；先在 Nexus 页面登录后即可正常浏览。

4. 用命令行查看（不离开终端）

bash

# 1. 看某个依赖的所有可用版本（需要 versions-maven-plugin）
mvn versions:display-dependency-updates

# 2. 看依赖树，确认实际用的是哪个版本、从哪来的
mvn dependency:tree

# 3. 只看某个包的来源
mvn dependency:tree -Dincludes=com.alibaba:fastjson2

# 4. 查看某个坐标在本地仓库的文件结构
dir %USERPROFILE%\.m2\repository\com\alibaba\fastjson2

# 5. 直接列远程仓库某目录（Linux / macOS 有 curl 时）
curl -s https://repo.maven.apache.org/maven2/com/alibaba/fastjson2/ | grep -o 'href="[^"]*"'

5. 快速定位坐标的技巧

场景	做法
只知道包名不知道 groupId	在 mvnrepository.com 直接搜包名，看 `Group / Artifact` 两列
想看有哪些版本可选	打开包详情页 → `Versions` 标签页（按时间倒序）
想确认是否被传递引入	`mvn dependency:tree -Dincludes=groupId:artifactId`
想知道为什么版本是这个	`mvn help:effective-pom` 看最终生效版本
想看依赖的许可证/漏洞	包详情页 `License` / `Vulnerabilities` 区块

💡 一句话：找包/查版本上 mvnrepository.com 或 central.sonatype.com；想看仓库「所有包」的原始目录，把任意仓库根地址当文件夹一层层点进去即可。

十、依赖作用域（scope）说明

<scope> 决定依赖在哪些阶段可见、是否打进最终包。

scope	编译期	测试期	运行期	打进包	典型场景
`compile`（默认）	✅	✅	✅	✅	大多数依赖，如 `spring-web`
`provided`	✅	✅	❌	❌	`lombok`、`servlet-api`（容器已提供）
`runtime`	❌	✅	✅	✅	JDBC 驱动 `mysql-connector-java`
`test`	❌	✅	❌	❌	`junit`、`mockito`、`spring-boot-starter-test`
`system`	✅	✅	✅	❌	本地 jar（需写 `systemPath`，不推荐）
`import`	—	—	—	—	仅用于 `<dependencyManagement>` 导入 BOM

示例：

xml

<!-- 编译期需要，运行时容器已提供 -->
<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <scope>provided</scope>
</dependency>

<!-- 只在测试代码里用 -->
<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <scope>test</scope>
</dependency>

<!-- 导入 Spring Boot BOM 统一版本 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-dependencies</artifactId>
  <version>2.7.18</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

💡 打包时想把 provided 依赖也带上（如用 assembly 打可执行包），需在插件里显式配置 includeScope。

十一、常用 Maven 命令速查

命令	作用
`mvn -v`	查看 Maven / JDK 版本
`mvn clean`	清理 `target` 目录
`mvn compile`	编译主代码
`mvn test`	跑单元测试
`mvn package`	打包（jar/war）
`mvn install`	打包并安装到本地仓库（供本机其它项目引用）
`mvn deploy`	打包并发布到远程仓库（私服）
`mvn clean package -DskipTests`	打包但跳过测试
`mvn clean package -Dmaven.test.skip=true`	连测试代码编译都跳过
`mvn clean package -Pprod`	激活 `prod` profile 打包
`mvn clean package -am -pl 模块名`	只构建指定模块及它依赖的模块
`mvn clean package -U`	强制更新 SNAPSHOT 依赖（解决「拉不到最新快照」）
`mvn clean package -o`	离线构建（只用本地仓库）
`mvn clean package -X`	打开 debug 日志（排查问题用）
`mvn dependency:tree`	打印依赖树（排查冲突）
`mvn dependency:tree -Dincludes=groupId:artifactId`	只看指定依赖的来源
`mvn dependency:analyze`	分析「用了没声明 / 声明了没用」的依赖
`mvn help:effective-pom`	查看合并父工程后的最终 pom（排查看不到父配置）
`mvn help:effective-settings`	查看合并后的最终 settings
`mvn versions:display-dependency-updates`	列出可升级的依赖版本
`mvn archetype:generate`	生成项目骨架
`mvn spring-boot:run`	直接启动 Spring Boot 应用

生命周期简述

1	clean → validate → compile → test → package → verify → install → deploy

mvn package 会自动依次执行前面所有阶段（validate/compile/test 等），所以一般不用单独跑 compile。

十二、依赖冲突排查与解决

1. 定位冲突

bash

1	mvn dependency:tree -Dverbose > tree.txt

重点看输出里的：

[INFO] com.example:demo:jar:1.0.0
[INFO] +- org.springframework:spring-core:jar:5.3.31:compile
[INFO] \- com.other:lib:jar:1.0.0:compile
[INFO]    \- (org.springframework:spring-core:jar:5.3.20:compile - omitted for conflict with 5.3.31)

omitted for conflict with xxx 就表示该版本被就近原则淘汰了。

2. Maven 依赖调解两大原则

原则	说明
最短路径优先	依赖路径短的胜出（直接依赖 > 传递依赖）
最先声明优先	路径长度相同时，pom 里先声明的胜出

3. 常见解决手段

xml

<!-- 方案一：显式声明想要的版本（最短路径优先，直接生效） -->
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-core</artifactId>
  <version>5.3.31</version>
</dependency>

<!-- 方案二：排除传递进来的旧版本 -->
<dependency>
  <groupId>com.other</groupId>
  <artifactId>lib</artifactId>
  <version>1.0.0</version>
  <exclusions>
    <exclusion>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

手段	适用场景
显式声明版本	想统一到某个版本
`<exclusions>`	某传递依赖完全不需要，或需换版本
`<dependencyManagement>`	父工程统一锁版本（推荐）
`<optional>true</optional>`	该依赖不向下游传递

4. 常见报错对照

报错	原因	处理
`Could not resolve dependencies`	仓库没有该版本 / 网络不通	换镜像源、`-U` 强制更新
`Non-resolvable parent POM`	父工程拉不到	检查父工程是否已 install 或镜像能否访问
`NoSuchMethodError` / `ClassNotFoundException`	依赖冲突（编译期一个版本、运行期另一个）	`dependency:tree` 找冲突，排除旧版本
`Artifact has not been packaged yet`	多模块构建顺序问题	加 `-am` 一起构建
`401 Unauthorized`	私服账号密码错	检查 `settings.xml` 的 `<server>`
`was cached in the local repository`	快照缓存过期	加 `-U` 强制更新
`invalid LOC header` / jar 损坏	下载中断	删掉本地仓库对应目录重新下

十三、多模块工程配置

大型项目常用「父 pom 管版本，子模块管依赖」结构：

demo-parent/
├── pom.xml                  <!-- packaging = pom -->
├── demo-common/
│   └── pom.xml
├── demo-service/
│   └── pom.xml
└── demo-web/
    └── pom.xml

父工程 pom.xml

xml

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>demo-parent</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>   <!-- 父工程必须是 pom -->

  <!-- 声明子模块 -->
  <modules>
    <module>demo-common</module>
    <module>demo-service</module>
    <module>demo-web</module>
  </modules>

  <!-- 统一锁版本，子模块引依赖不写 version -->
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>demo-common</artifactId>
        <version>${project.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

子模块 pom.xml

xml

<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.example</groupId>
    <artifactId>demo-parent</artifactId>
    <version>1.0.0</version>
    <!-- 默认找上级目录的 pom，同目录结构可省略 -->
    <relativePath>../pom.xml</relativePath>
  </parent>

  <artifactId>demo-service</artifactId> <!-- groupId/version 继承父工程，无需重复写 -->

  <dependencies>
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>demo-common</artifactId> <!-- 版本由父工程管理 -->
    </dependency>
  </dependencies>
</project>

只构建某个模块（含它依赖的模块）：

bash

1	mvn clean package -am -pl demo-web

参数	含义
`-pl`	指定要构建的模块（`--projects`）
`-am`	同时构建该模块依赖的模块（`--also-make`）
`-amd`	同时构建依赖该模块的模块（`--also-make-dependents`）

十四、常见问题 FAQ

Q1：改了 settings.xml 不生效？

确认改的是 IDEA 里 User settings file 指向的那个（IDEA 可能覆盖了默认路径）；
IDEA 里勾选 Settings → Maven → Always update snapshots 或执行 Reload All Maven Projects；
命令行执行 mvn help:effective-settings 看最终生效的配置。

Q2：依赖明明下了却报找不到？

检查是否被 <scope>provided / test</scope> 限制；
检查是否被 <optional>true</optional> 且你是下游项目；
执行 mvn dependency:tree 确认是否真的引入了。

Q3：SNAPSHOT 更新不及时？

加 -U 强制更新：mvn clean package -U；
或删掉本地仓库中对应 SNAPSHOT 目录后重新构建；
IDEA 中执行 Settings → Maven → Always update snapshots。

Q4：IDEA 右侧 Maven 面板不显示 / 依赖爆红？

右键 pom.xml → Add as Maven Project；
检查 Maven home path 是否指向正确；
删掉 .idea 目录重新导入项目。

Q5：想跳过测试但还想编译测试代码？

-DskipTests：编译测试代码，但不执行（推荐）；
-Dmaven.test.skip=true：连测试代码都不编译（更快）。

Q6：本地仓库里一堆 .lastUpdated 文件导致下载失败？

.lastUpdated 表示「上次下载失败」，Maven 在超时周期内不会重试。清理方法：

bash

# Windows（在本地仓库目录下执行）
for /r %i in (*.lastUpdated) do del %i

# Linux / macOS
find ~/.m2/repository -name "*.lastUpdated" -delete

然后重新 mvn clean package -U。

Q7：如何让 Maven 用指定 JDK 编译？

三种方式（优先级从低到高）：

xml

<!-- 1. settings.xml 全局 profile -->
<profile>
  <id>jdk-8</id>
  <activation><activeByDefault>true</activeByDefault></activation>
  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
  </properties>
</profile>

<!-- 2. 项目 pom 的 properties（推荐） -->
<properties>
  <maven.compiler.source>8</maven.compiler.source>
  <maven.compiler.target>8</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<!-- 3. 编译插件显式指定 -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.11.0</version>
  <configuration>
    <source>8</source>
    <target>8</target>
    <encoding>UTF-8</encoding>
  </configuration>
</plugin>

十五、配置检查清单

配置完成后逐项核对：

#	检查项	命令 / 位置
1	JDK 已安装且版本 ≥ 8	`java -version`
2	Maven 环境变量 `MAVEN_HOME` + `Path` 配好	`mvn -v`
3	本地仓库已改到非系统盘	`settings.xml` 的 `<localRepository>`
4	已配国内镜像	`settings.xml` 的 `<mirrors>`
5	镜像未误伤私服	`<mirrorOf>` 用 `*,!私服id`
6	编码统一 UTF-8	pom 的 `<project.build.sourceEncoding>`
7	IDEA 指向自定义 settings.xml	`Settings → Maven → User settings file`
8	依赖树无冲突	`mvn dependency:tree`
9	最终配置符合预期	`mvn help:effective-settings`、`mvn help:effective-pom`

💡 一句话记住三个文件的职责：**settings.xml 管「从哪下、下到哪、用什么账号」；pom.xml 管「依赖什么、怎么打包、发到哪」；环境变量管「mvn 命令能不能被找到」。**

Maven 下载与配置完全指南

一、下载 Maven

二、配置环境变量

Windows

三、验证安装

四、配置阿里云镜像（必做）

五、配置本地仓库（建议做）

六、在 IDEA 中集成

七、settings.xml 完整结构与常用标签

完整示例（可直接替换）

settings.xml 标签速查

<mirrorOf> 常用写法（易踩坑）

八、pom.xml 核心标签详解

pom.xml 标签速查

<distributionManagement>（发布用）

九、仓库地址大全

官方中央仓库

阿里云镜像（推荐）

其它国内镜像

镜像 vs 仓库：配置位置不同

查看仓库所有包的地址（在线浏览 / 搜索）

1. 在线搜索平台（最常用）

2. 直接浏览仓库目录（看「所有包」）

3. 私服（Nexus / Artifactory）浏览地址

4. 用命令行查看（不离开终端）

5. 快速定位坐标的技巧

十、依赖作用域（scope）说明

十一、常用 Maven 命令速查

生命周期简述

十二、依赖冲突排查与解决

1. 定位冲突

2. Maven 依赖调解两大原则

3. 常见解决手段

4. 常见报错对照

十三、多模块工程配置

十四、常见问题 FAQ

十五、配置检查清单

`<mirrorOf>` 常用写法（易踩坑）

`<distributionManagement>`（发布用）