构建与依赖 / 系统课时
离线构建与缓存刷新
离线构建与缓存刷新
这节解决两类常见问题:断网后 Maven 怎样只靠本地缓存完成构建,以及缓存了旧 SNAPSHOT、失败下载或异常 release 时怎样精准刷新。完成后,你会区分 -o、-U 和 updatePolicy 的职责,并避免用“删整个 .m2”处理单个依赖问题。
学习目标
- 在联网阶段预热本地仓库,并验证同一项目能否使用
-o完成离线构建。 - 正确使用
-U与updatePolicy处理 SNAPSHOT、缺失 release 和失败下载缓存。 - 对单个异常依赖执行定点清理和重新解析,而不是无差别删除全部本地仓库。
先把离线构建需要的内容准备齐
Maven 默认把已解析的构件保存在 ~/.m2/repository。-o 或 --offline 只允许使用本地已有内容;缺少依赖、父 POM、构建插件或插件自身依赖时,离线模式不会偷偷联网,而是直接失败。因此预热必须使用与离线构建相同的 POM、Profile、JDK 和 settings.xml。
联网环境先执行 Maven Dependency Plugin 3.11.0 的 go-offline,把当前项目需要的依赖和构建插件尽量解析到本地仓库:
mvn -B -ntp org.apache.maven.plugins:maven-dependency-plugin:3.11.0:go-offline预期结果:
[INFO] BUILD SUCCESS随后立即断开网络或在同一工作区执行真正的离线验证:
mvn -o -B -ntp verify预期结果:
[INFO] BUILD SUCCESS如果第二条命令失败,先读报错中的第一个缺失坐标。最常见原因是预热时没有激活离线构建实际使用的 Profile,或某个插件会在执行阶段动态解析额外构件。此时应补齐相同的 -P、-s 等参数重新预热,而不是把失败归因于 -o 本身。

用 -U 处理快照与失败缓存
-U 即 --update-snapshots。在 Maven 3.9.x 中,它会强制检查远程仓库中的更新 SNAPSHOT,并重新检查缺失的 release;因此它适合处理“私服刚发布了同版本 SNAPSHOT”或“上次下载失败后本地记住了失败结果”的情况,但它不是“重新下载所有 release”。
mvn -U -B -ntp verify预期结果:远程仓库可访问、项目依赖有效时,最终应出现:
[INFO] BUILD SUCCESS本地仓库中的失败解析常会伴随 .lastUpdated 等状态文件。遇到 “failure was cached” 一类提示时,先用 -U 重试;如果根因其实是 401、407、DNS 或 TLS 错误,-U 只会更快地再次失败,仍要先修复认证或网络。
| 现象 | 首选动作 | 不建议动作 |
|---|---|---|
| SNAPSHOT 刚发布新内容 | mvn -U verify |
删除整个 ~/.m2/repository |
| 上次远程临时不可用,当前已恢复 | mvn -U verify |
改项目版本号绕过缓存 |
| 已存在的 release JAR 本身损坏 | 定点删除该构件后重新解析 | 期望 -U 自动覆盖所有 release |
| 当前完全无网络 | mvn -o verify |
反复执行 -U |
用 updatePolicy 控制日常刷新频率
仓库策略可以分别配置 release 与 SNAPSHOT 的更新频率。有效值包括 always、daily、interval:X 和 never;其中 X 是分钟数,默认策略通常为 daily。对频繁发布的内部 SNAPSHOT,可以把检查间隔设为 15 分钟,而不必让每次构建都强制 -U。
<settings>
<profiles>
<profile>
<id>corp-repositories</id>
<repositories>
<repository>
<id>corp-snapshots</id>
<url>https://repo.corp.example/repository/maven-snapshots/</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>interval:15</updatePolicy>
</snapshots>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>corp-repositories</activeProfile>
</activeProfiles>
</settings>这份配置只开放 SNAPSHOT,并在正常在线构建中按 15 分钟间隔检查更新。always 适合极少数需要每次都追踪最新快照的场景,但会增加元数据请求;never 表示本地已有内容后不再按策略检查更新,通常只适合不可变或严格受控的仓库。
验证策略时不要只看 POM:如果团队使用 -s ./ci/settings.xml,应确认流水线传入的就是包含该 Profile 的文件。临时执行 -U 可以强制本次检查,但不应把它当成永久替代 updatePolicy 的默认构建参数。
只清理坏掉的坐标
如果只有 com.acme:demo-lib 的本地副本可疑,优先定点清理。Maven Dependency Plugin 的 purge-local-repository 可以只删除手工指定的构件,再由下一次构建重新解析;这比删除整个仓库更快,也不会让所有插件和依赖重新下载。
mvn -B -ntp org.apache.maven.plugins:maven-dependency-plugin:3.11.0:purge-local-repository -DmanualInclude=com.acme:demo-lib -DreResolve=false
mvn -U -B -ntp verify预期结果:第一条命令完成定点清理,第二条重新下载项目实际需要的版本;两次 Maven 调用都应分别以成功状态结束:
[INFO] BUILD SUCCESSmanualInclude 按 groupId:artifactId 指定清理对象,因此同一 artifact 的本地缓存可能被一起移除;如果你只想删除某个确定版本,可直接定位 ~/.m2/repository/com/acme/demo-lib/<VERSION>/,确认坐标无误后只删除这个版本目录,再执行 mvn -U verify。
验收标准是可重复的:先联网预热,再用 mvn -o verify 成功一次;随后模拟一个 SNAPSHOT 更新,用 mvn -U verify 获取新内容;最后对单个异常构件做定点清理并恢复成功。这样可以明确区分“缓存缺失”“更新策略”和“本地构件损坏”三种问题。