A02 Maven 基础配置：本地仓库、镜像、项目编码与常见问题（IDEA 实战）

【本节目标】

学完这一篇，你应该能做到：

1）理解 Maven 的本地仓库、远程仓库、镜像（mirror）到底在解决什么问题

2）配置 Maven 的本地仓库路径（避免 C 盘爆炸 / 便于迁移）

3）配置国内镜像（提升依赖下载速度）

4）在 IDEA 中正确设置 Maven（Maven Home、User settings、Local repository、Runner JDK）

5）统一项目编码（UTF-8）并解决常见乱码/依赖下载失败/编译版本不一致等问题

一、Maven 的"工作方式"先记住这一张逻辑

你可以把 Maven 理解成"依赖下载 + 项目构建"的统一工具。

它最核心的流程是：

1）你在 pom.xml 里声明依赖（依赖坐标）

2）Maven 去远程仓库下载 jar

3）下载后放到"本地仓库"里缓存

4）构建时从本地仓库读取依赖参与编译/运行/打包

所以：

本地仓库 = 你电脑上的依赖缓存（默认在 C 盘用户目录）
远程仓库 = Maven 官方/公司私服等
镜像 = 给远程仓库加一个"更快的入口"（常见是国内镜像）

二、先把本地仓库挪到一个"长期稳定"的路径

默认本地仓库在：

C:\Users\你的用户名.m2\repository

这会导致：C 盘变大、迁移麻烦、重装后还得重新下载。

建议路径（任选一种）：

D:\dev\maven-repo
D:\m2\repository
E:\maven\repo

（只要别放中文路径，稳定就行）

配置方式（最通用）：修改 settings.xml

你要找到你的 Maven settings.xml（通常有两个位置）：

1）全局：Maven 安装目录 conf/settings.xml

2）用户级：C:\Users\你的用户名.m2\settings.xml（推荐使用用户级）

推荐：使用用户级 settings.xml（更不容易被覆盖）。

在 settings.xml 里加上：

XML 复制代码

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

注意：

三、配置镜像（加速依赖下载）

如果你经常遇到"下载很慢/卡住"，大概率需要配置镜像。

在 settings.xml 的 <mirrors> 里加：

XML 复制代码

<mirrors>
  <mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>Aliyun Maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

说明：

mirrorOf 为 * 表示镜像所有仓库请求
有些公司网络会要求走公司私服（Nexus/Artifactory），那就按公司要求替换 url

四、IDEA 里 Maven 必须确认的 4 个设置（很关键）

路径参考（不同版本 IDEA 入口略有差别，但大体一致）：

Settings → Build, Execution, Deployment → Build Tools → Maven

你要检查以下四项：

1）Maven home path

选择你安装的 Maven 或 IDEA 自带 Maven

（不确定就先用 IDEA Bundled Maven）

2）User settings file

指向你刚修改的 settings.xml（用户级的那个）

例如：C:\Users\xxx.m2\settings.xml

3）Local repository

这里最好会自动读取 localRepository

如果没有自动变，手动选择 D:\dev\maven-repo

4）Runner（非常容易忽略）

Settings → Build Tools → Maven → Runner

JRE：建议选你项目的 JDK（比如 JDK 17）

不然会出现：项目用 17，但 Maven 编译用 8 → 报错很诡异

五、统一项目的编译版本（避免"能跑但编译报错"）

很多人会遇到这种情况：

IDEA 运行没问题，但 Maven 打包/CI 编译报错。

原因通常是 pom.xml 没明确指定 Java 编译版本，或 Maven 用了低版本 JDK。

建议在 pom.xml 里明确声明（适配 JDK 17 举例）：

XML 复制代码

<properties>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

如果你现在公司项目是 JDK 8，就把 17 改成 8。

六、统一编码（UTF-8）并解决乱码问题

乱码常见原因有三个：

1）源文件编码不是 UTF-8

2）Maven 构建编码没设置

3）控制台输出编码和源文件不一致

建议统一做法：

1）IDEA 设置为 UTF-8

Settings → Editor → File Encodings

Global Encoding：UTF-8
Project Encoding：UTF-8
Default encoding for properties files：UTF-8

（如果你项目有中文 properties，可能还要勾 "Transparent native-to-ascii conversion" 视情况）

2）pom.xml 写死编码（上一节 properties 已写）

project.build.sourceEncoding = UTF-8

3）运行配置遇到控制台乱码时

在 Run Configuration 里把 VM options 加：-Dfile.encoding=UTF-8

（这个不是每个项目都需要，但遇到再用）

七、Maven 常见问题与排查（建议收藏）

问题 1：依赖一直下载失败 / 卡在某个 jar

排查建议：

看是否镜像配置生效（settings.xml 路径是否正确）
检查网络/代理（公司网络有时需要配置代理或走私服）
右键项目 Maven → Reimport
删除本地仓库里对应的"失败目录"再重新下载

问题 2：Could not transfer artifact / 403 / 502

原因：镜像不稳定、公司网络限制、仓库不可用

解决：更换镜像源、走公司私服、或临时切回中央仓库测试

问题 3：Dependency not found / 版本不存在

原因：依赖坐标写错、版本不存在、仓库范围不包含

解决：复制官方坐标、查看 Maven Central、或加私服仓库

问题 4：编译报错 "release version xx not supported"

原因：Maven Runner 的 JDK 版本太低

解决：IDEA Maven Runner 改成正确的 JDK

问题 5：本地仓库改了但依赖还在旧路径

原因：IDEA 仍指向旧 settings.xml

解决：确认 User settings file 的路径 + 重启 IDEA + Reimport

八、本节小结

1）Maven 三个关键概念：本地仓库、远程仓库、镜像

2）建议把本地仓库挪到非系统盘（D/E 盘）

3）配置国内镜像显著提升下载速度

4）IDEA 的 Maven Runner JDK 很关键，别忽略

5）pom.xml 中明确 Java 版本与 UTF-8 编码，避免构建差异

下一篇预告（A03）

《A03 变量与数据类型：类型转换、精度丢失与常见坑（带最小示例）》

把基础打牢，后面集合/并发/JVM 会顺很多。

【settings.xml：本地仓库】

XML 复制代码

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

【settings.xml：镜像】

XML 复制代码

<mirrors>
  <mirror>
    <id>aliyunmaven</id>
    <mirrorOf>*</mirrorOf>
    <name>Aliyun Maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

【pom.xml：编译版本与编码】

XML 复制代码

<properties>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>