构建与依赖 / 系统课时
本地仓库与中央仓库
本地仓库与中央仓库
这一课把 Maven 解析依赖时最容易混淆的两件事拆开:它先查哪里,以及一个坐标最终落到本地哪个目录。完成后,你可以用命令验证本地仓库位置、主动拉取一个制品,并根据坐标直接定位缓存文件。
学习目标
- 说清本地仓库、远程仓库与 Central 在依赖解析中的关系。
- 根据
groupId:artifactId:version推导本地仓库路径。 - 用 Maven 命令拉取制品并验证缓存是否存在。
Maven 实际从哪里找依赖
Maven 解析普通依赖时先检查本地仓库;本地没有可用制品时,再访问当前构建生效的远程仓库。默认 Super POM 定义了 ID 为 central 的中央仓库,地址是 https://repo.maven.apache.org/maven2,但 settings.xml 中的 mirror 可以把它重定向到公司仓库。
例如项目需要 org.apache.commons:commons-lang3:3.14.0。若 JAR 已在本地仓库,Maven 可直接使用;若不存在,就根据有效仓库列表下载,成功后写入本地仓库,后续构建通常直接复用缓存。离线模式只允许使用本地已有内容,缺失依赖会直接失败。

坐标怎样映射到本地目录
默认本地仓库位于用户目录下的 .m2/repository。映射规则很机械:groupId 中的点换成目录分隔符,再依次拼接 artifactId 与 version,文件名通常采用 artifactId-version.extension。
以 org.apache.commons:commons-lang3:3.14.0 为例,默认 JAR 路径就是 ~/.m2/repository/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar。同一目录还可能出现 POM、校验文件、_remote.repositories 或元数据文件,它们用于保存描述信息和解析来源。
如果团队通过 settings.xml 的 <localRepository> 修改了位置,就不要再假设仓库一定在 ~/.m2。最稳妥的方式是读取 Maven 当前生效的 settings.localRepository,而不是根据操作系统用户名手工拼接路径。
用命令验证本地缓存
下面示例适用于 macOS、Linux 或其他 Bash 环境。它先取得实际本地仓库路径,再下载 Commons Lang 3.14.0,最后检查目标 JAR 是否已经落盘;首次执行需要能够访问当前配置的远程仓库。
LOCAL_REPO="$(mvn -q help:evaluate -Dexpression=settings.localRepository -DforceStdout)"
echo "LOCAL_REPO=$LOCAL_REPO"
mvn -q dependency:get -Dartifact=org.apache.commons:commons-lang3:3.14.0 -Dtransitive=false
test -f "$LOCAL_REPO/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar" && echo "artifact cached"预期输出:
LOCAL_REPO=<PATH>
artifact cached<PATH> 会替换成当前机器的真实仓库目录。这里使用 -Dtransitive=false,因此只验证目标制品本身;去掉该参数后,dependency:get 还会继续解析传递依赖,实际下载的文件数量会增加。
解析异常先检查哪一层
遇到“本地明明有文件但 Maven 仍访问网络”时,先检查 effective settings 中的 mirror、proxy、本地仓库路径和远程仓库配置,再核对坐标。artifactId、版本号、classifier 或扩展名只要不同,就属于不同制品,目录中存在相似文件并不能满足解析请求。
不要把本地仓库当成普通依赖目录手工维护。自己的项目制品应通过 Maven 的 install 阶段写入本地仓库;远程依赖则交给解析器下载。这样 Maven 才能同时维护 POM、元数据和来源记录,避免出现只有 JAR、没有配套描述信息的残缺缓存。