快照版本机制

本章承接入门教程对 SNAPSHOT 的初步介绍，深入讲解 Maven 的动态版本解析机制。入门已了解 SNAPSHOT 表示"开发中版本"，本章将掌握快照的更新策略、本地缓存行为、远程元数据结构，以及它与 RELEASE 版本在团队协作中的本质差异。

核心机制

SNAPSHOT（快照）版本是 Maven 为持续迭代开发设计的特殊版本号格式。它的核心特征是可变性：同一个版本坐标（如 1.0.0-SNAPSHOT）在不改变坐标的情况下，可以多次发布新的构建产物。

为什么需要 SNAPSHOT？

假设团队正在开发 payment-service 的 1.0.0 版本，每天提交 5 次代码。如果每次提交都升级版本号（1.0.0-alpha-1、1.0.0-alpha-2……），依赖方（如 order-service）的 pom.xml 就要每天改 5 次版本号，这是不可接受的。

SNAPSHOT 的解决方案是：依赖方固定写 1.0.0-SNAPSHOT，Maven 自动去远程仓库检查是否有更新的构建。

快照版本号的结构

SNAPSHOT 版本号以 -SNAPSHOT 结尾，Maven 会将其解析为带有时间戳和构建号的唯一文件名：

1.0.0-SNAPSHOT
  ↓ 部署到远程仓库后
payment-service-1.0.0-20240611.143022-1.jar
payment-service-1.0.0-20240611.154511-2.jar
payment-service-1.0.0-20240612.090145-3.jar

远程仓库中的 maven-metadata.xml 记录了所有快照构建的列表，以及最新版本的指向。

本地快照缓存与更新策略

Maven 不会每次构建都去远程检查 SNAPSHOT，而是遵循 updatePolicy：

updatePolicy 在 settings.xml 的仓库配置中设置：

<repositories>
    <repository>
        <id>company-snapshots</id>
        <url>http://nexus.feixiang.tech/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
    </repository>
</repositories>

远程快照元数据

远程仓库中每个 SNAPSHOT 构件目录下都有一个 maven-metadata.xml：

<metadata>
    <groupId>com.feixiang</groupId>
    <artifactId>payment-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <versioning>
        <snapshot>
            <timestamp>20240611.154511</timestamp>
            <buildNumber>2</buildNumber>
        </snapshot>
        <lastUpdated>20240611154511</lastUpdated>
        <snapshotVersions>
            <snapshotVersion>
                <extension>jar</extension>
                <value>1.0.0-20240611.154511-2</value>
                <updated>20240611154511</updated>
            </snapshotVersion>
        </snapshotVersions>
    </versioning>
</metadata>

这个文件是 Maven 判断"远程是否有更新"的唯一依据。本地仓库也会缓存一份该文件，并记录下载时间，用于与 updatePolicy 对比。

生活类比：期刊订阅与每日报纸

• RELEASE 版本像一本精装书：出版后内容固定，ISBN 编号唯一。你买回家，书架上永远是一本确定的书。
• SNAPSHOT 版本像一份日报：每天内容都在更新，但报摊位置（坐标）不变。你每天早上路过报摊，如果看到今天的报纸到了（updatePolicy 触发），就买一份新的；如果今天已经买过了（本地缓存有效），就直接看手里的。

Maven 的 updatePolicy 就是你"多久去一次报摊"的规则。

图示

上图展示了 SNAPSHOT 的解析流程：本地首先检查缓存有效期（由 updatePolicy 决定），如果过期或强制更新，则下载远程的 maven-metadata.xml 比对构建号。远程仓库中，同一 SNAPSHOT 坐标下可以存在多个带时间戳的构建文件，元数据文件负责指向最新版本。

完整示例

场景

飞翔科技的 payment-service 和 order-service 由不同小组并行开发。order-service 依赖 payment-service。后端小崔负责 payment-service，前端黄俪在 order-service 中集成支付接口，架构师白歌制定版本策略，运维李眉管理 Nexus 私服。

SNAPSHOT 与 RELEASE 对比

白歌在团队规范中明确了两者的使用边界：

操作：小崔发布快照，黄俪消费快照

步骤 1：小崔发布 SNAPSHOT

payment-service 的 pom.xml：

<project>
    <groupId>com.feixiang</groupId>
    <artifactId>payment-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <!-- ... -->
</project>

小崔提交代码后执行：

mvn clean deploy

Nexus 私服收到构建，文件结构如下：

maven-snapshots/com/feixiang/payment-service/1.0.0-SNAPSHOT/
├── maven-metadata.xml
├── payment-service-1.0.0-20240611.143022-1.jar
├── payment-service-1.0.0-20240611.143022-1.pom
├── payment-service-1.0.0-20240611.154511-2.jar
└── payment-service-1.0.0-20240611.154511-2.pom

步骤 2：黄俪在 order-service 中依赖快照

<dependencies>
    <dependency>
        <groupId>com.feixiang</groupId>
        <artifactId>payment-service</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
</dependencies>

黄俪第一次构建时，Maven 下载了 buildNumber=2 的快照。第二天小崔修复了一个 Bug，发布了 buildNumber=3。黄俪再次构建时：

• 如果 updatePolicy 是 daily 且今天已经构建过：黄俪不会自动拿到最新版，仍用本地的 buildNumber=2
• 如果黄俪想强制更新：执行 mvn clean compile -U（-U 表示强制更新快照）

步骤 3：转正为 RELEASE

联调完成后，白歌要求小崔将版本改为 RELEASE：

mvn versions:set -DnewVersion=1.0.0
mvn clean deploy

此时 payment-service-1.0.0.jar 被部署到 maven-releases 仓库。黄俪将 order-service 中的依赖改为：

<version>1.0.0</version>

RELEASE 版本一旦发布，内容永远固定。李眉在 Nexus 上开启"禁止重复部署"策略，确保 1.0.0 不会被意外覆盖。

易错点与常见问题

误区一：SNAPSHOT 可以随便用，反正会更新

错误认知："开发阶段全部用 SNAPSHOT 就行，Maven 会自动保持最新。"

纠正：SNAPSHOT 的自动更新受 updatePolicy 严格限制。默认 daily 意味着：如果你上午 9 点构建过一次，同事 10 点发布了新快照，你 11 点再次构建时不会自动拿到最新版，要等到第二天。这会导致"我这边明明已经修复了，你那边怎么还是旧的"的诡异问题。

正确做法：

• 本地开发频繁联调时，使用 mvn ... -U 强制更新
• 在 CI/CD 流水线中，快照构建阶段统一加 -U 参数
• 关键集成测试前，手动清理本地仓库中的快照缓存：rm -rf ~/.m2/repository/com/feixiang/payment-service/1.0.0-SNAPSHOT/

误区二：RELEASE 版本也能覆盖重发

错误认知："我发现 1.0.0 有个小 Bug，我改一下重新 deploy 覆盖掉。"

纠正：Maven 的 RELEASE 仓库默认不允许重复部署同一坐标。即使私服管理员强行开启覆盖，这也是极度危险的操作——因为依赖 1.0.0 的其他项目可能已经缓存了旧文件，它们永远不会知道文件内容变了，导致"同一版本号，不同内容"的不可复现灾难。

反例：李眉曾在 Nexus 上误开启"允许覆盖 RELEASE"，小崔重新 deploy 了 1.0.0。白歌的笔记本上缓存了旧的 1.0.0，生产环境 CI 下载了新的 1.0.0，两者行为不一致，导致线上故障。RELEASE 版本一旦发布，有问题只能发 1.0.1，绝对不可覆盖。

误区三：本地仓库的快照永远不会过期

错误认知："我本地已经下载了 SNAPSHOT，它会一直自动保持最新。"

纠正：本地快照的更新完全受 updatePolicy 控制。如果设置为 never，或者你在离线环境，本地快照将永远停留在第一次下载的版本。更隐蔽的是：即使 updatePolicy 是 daily，如果远程仓库的 maven-metadata.xml 下载失败（网络抖动），Maven 会静默使用本地缓存，不会报错。

排查方法：

# 查看本地缓存的快照元数据
cat ~/.m2/repository/com/feixiang/payment-service/1.0.0-SNAPSHOT/maven-metadata-local.xml

如果 lastUpdated 是三天前的，而你知道远程已经发布了新版本，说明本地缓存没有刷新。

小结

SNAPSHOT 是 Maven 为持续迭代开发设计的动态版本机制。它通过 -SNAPSHOT 后缀标识可变构建，远程仓库用 maven-metadata.xml 管理多个时间戳构建，本地仓库按 updatePolicy 控制刷新频率。SNAPSHOT 适用于开发联调阶段，RELEASE 适用于稳定交付阶段，两者在可重复部署性、缓存策略和团队协作语义上有本质区别。理解并正确配置 updatePolicy、合理使用 -U 强制更新、严格遵守 RELEASE 不可覆盖原则，是团队级依赖管理的基本纪律。

本章与全局的关系：本章回答了"开发阶段如何管理频繁变化的版本"。下一章"仓库组与路由"将深入讲解企业级私服（如 Nexus）的仓库组织方式，理解仓库组如何让开发者在"一个 URL"背后透明地访问多个物理仓库。