本地仓库

本章承接"仓库体系"，聚焦 Maven 最贴近开发者的仓库——本地仓库。理解本地仓库的物理结构、GAV 到路径的映射规则，是排查依赖问题、手动清理冗余构件、配置多环境隔离的基础。

核心机制

本地仓库是你本机上的一个副本，既缓存远程下载的构件，也包含你尚未发布的临时构建产物。注意两个关键词——cache（缓存）和 temporary build artifacts（临时构建产物）。本地仓库不仅是"下载来的 JAR 的存放处"，也是你运行 mvn install 后，自己项目产出的 JAR 的"临时归宿"。

默认位置与平台差异

Maven 启动时，如果没有显式配置 localRepository，会按以下规则确定本地仓库位置：

操作系统	默认路径
Windows	`C:\Users\<用户名>\.m2\repository`
Linux / macOS	`~/.m2/repository`

这个路径中的 .m2 目录同时存放两个文件：

repository/ —— 本地仓库的根目录，所有构件按 GAV 层级存放
settings.xml —— 用户的私有配置（如镜像、私服认证、本地仓库路径自定义）

localRepository 配置

如果你希望将本地仓库移到别的位置（如换到更大的磁盘、避免 C 盘空间不足），可以在 settings.xml 中修改：

<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
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>D:/maven-repo</localRepository>
</settings>

注意：settings.xml 有两个层级——

全局配置：$MAVEN_HOME/conf/settings.xml（影响所有用户）
用户配置：~/.m2/settings.xml（仅影响当前用户，优先级更高）

推荐在用户配置中修改 localRepository，避免影响同一台机器上的其他开发者。

仓库目录结构：GAV 到物理路径的映射

本地仓库的目录组织是 Maven 最核心的设计之一。给定一个坐标：

groupId: com.feixiang
artifactId: employee-system
version: 1.0.0
packaging: jar

它在本地仓库中的物理路径为：

~/.m2/repository/
└── com/
    └── feixiang/
        └── employee-system/
            └── 1.0.0/
                ├── employee-system-1.0.0.jar
                ├── employee-system-1.0.0.pom
                ├── employee-system-1.0.0-sources.jar
                ├── employee-system-1.0.0-javadoc.jar
                └── _remote.repositories

映射规则：

坐标元素	路径规则	示例
`groupId`	点号 `.` 替换为路径分隔符 `/`	`com.feixiang` → `com/feixiang`
`artifactId`	直接作为目录名	`employee-system` → `employee-system/`
`version`	直接作为目录名	`1.0.0` → `1.0.0/`
构件文件	`artifactId-version.packaging`	`employee-system-1.0.0.jar`

这个设计保证了全球任何 Maven 项目、任何开发者机器上，同一个 GAV 坐标对应的物理路径完全一致。这是 Maven 实现"可复现构建"的物理基础。

生活类比：图书馆的索书号系统

想象你去国家图书馆借一本书：

GAV 坐标 = 索书号：I247.5/1234 这样的编号唯一标识一本书
本地仓库路径 = 书架位置：索书号 I247.5/1234 对应"文学类（I）→ 长篇小说（247.5）→ 第 1234 号书架"。无论谁去借这本书，按索书号找，最终都会走到同一个书架的同一层
_remote.repositories：这本书的"借阅记录"，记录了这本书是从哪个图书馆（中央仓库、阿里云镜像、还是公司私服）借来的。下次需要更新时，Maven 知道该去问谁

这个类比的关键在于：GAV 不是随意命名的字符串，而是一套严格的地址编码系统。只要坐标确定，路径就确定，工具就能自动定位，无需人工干预。

图示

上图展示了 GAV 坐标到本地仓库物理路径的完整映射过程。这个映射是确定性的——给定相同的 GAV，任何机器、任何时刻生成的路径都相同。这也是 Maven 能在不同开发者之间共享依赖的底层机制。

完整示例

场景

飞翔科技的后端工程师小崔在排查一个诡异的构建问题：项目 pom.xml 里声明了 employee-system 1.0.0，但编译时却报错 package com.feixiang.employee does not exist。架构师白歌怀疑本地仓库里的构件文件损坏，让小崔去本地仓库检查。

操作前：不知道本地仓库在哪

小崔是 Windows 用户，从未关注过本地仓库的位置。他只知道 Maven "自动管理依赖"，但不清楚这些 JAR 到底存在哪里、长什么样。

操作步骤

步骤 1：确认本地仓库位置

小崔执行命令查看当前生效的本地仓库路径：

mvn help:evaluate -Dexpression=settings.localRepository -q -DforceStdout

输出：

C:\Users\xiaocui\.m2\repository

步骤 2：按 GAV 定位构件目录

根据报错信息，缺失的包属于 com.feixiang:employee-system:1.0.0。小崔按 GAV 映射规则找到对应目录：

C:\Users\xiaocui\.m2\repository
└── com
    └── feixiang
        └── employee-system
            └── 1.0.0

步骤 3：检查目录内容

小崔发现 1.0.0/ 目录下只有这些文件：

1.0.0/
├── employee-system-1.0.0.pom          # 只有 2KB，正常
├── employee-system-1.0.0.jar          # 只有 1KB，异常！正常应该 > 50KB
├── employee-system-1.0.0.jar.sha1     # 校验文件
└── _remote.repositories               # 记录来源

employee-system-1.0.0.jar 只有 1KB，明显是一个损坏的下载（可能是上次构建时网络中断导致的）。

步骤 4：清理并重新下载

小崔删除整个 1.0.0/ 目录：

# Windows
rmdir /s /q "C:\Users\xiaocui\.m2\repository\com\feixiang\employee-system\1.0.0"

# Linux/macOS
rm -rf ~/.m2/repository/com/feixiang/employee-system/1.0.0

然后重新执行构建：

mvn compile

操作结果

Maven 重新从阿里云镜像下载 employee-system-1.0.0.jar，这次文件大小为 68KB。编译顺利通过，报错消失。

变化分析：

小崔通过理解 GAV→路径的映射规则，精准定位到问题构件，而不是盲目删除整个本地仓库
_remote.repositories 文件让 Maven 知道该去哪个远程源重新下载
这次排查后，小崔在团队内部分享了"按 GAV 查本地仓库"的技巧，前端黄俪和运维李眉也学会了自助解决类似问题

易错点与常见问题

误区一：本地仓库可以随便整个删除

错误认知："构建出问题了，我把 ~/.m2/repository 整个删掉，让 Maven 重新下载，肯定能好。"

纠正：删除整个本地仓库确实能"重置"状态，但代价极大：

下次构建需要重新下载所有依赖，可能耗时数十分钟
你自己 mvn install 的私有构件也会丢失，其他引用这些构件的项目会报错
某些不稳定的网络环境下，重新下载可能再次失败

正确做法：按 GAV 精准定位问题构件，只删除有问题的版本目录。如本例所示，只删 com/feixiang/employee-system/1.0.0/，保留其他所有已缓存的依赖。