Maven Wrapper 如何保证团队和 CI 构建一致？

Maven Wrapper 的作用很直接：项目自己带一套启动脚本，第一次执行时下载指定版本的 Maven，以后团队成员和 CI 都用同一个 Maven 版本构建。它解决的不是依赖版本问题，而是构建工具版本问题。很多“我本地能构建、你那里不行”的问题，根源不是代码，而是 Maven 3.6、3.8、3.9 对插件解析、HTTP 仓库拦截、传输协议的行为不同。

如何添加 Maven Wrapper

在已有 Maven 的机器上执行一次：

bash
mvn -N wrapper:wrapper -Dmaven=3.9.6

生成后的文件应提交到版本库：

text
.mvn/wrapper/maven-wrapper.properties
.mvn/wrapper/maven-wrapper.jar
mvnw
mvnw.cmd

maven-wrapper.properties 里最关键的是 distributionUrl：

properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.3.2/maven-wrapper-3.3.2.jar

之后本地和 CI 都不要再直接写 mvn clean install，而是写：

bash
./mvnw -B clean verify

Windows 使用：

bat
mvnw.cmd -B clean verify

如果项目需要固定 JVM 参数，可以放在 .mvn/jvm.config；如果需要默认 Maven 参数，可以放在 .mvn/maven.config。例如：

text
文件：.mvn/maven.config
--no-transfer-progress
-Dstyle.color=always

CI 配置也很简单：

yaml
name: Maven Wrapper CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
          cache: maven
      - run: chmod +x mvnw
      - run: ./mvnw -B clean verify

企业内网环境常见问题是无法访问 Maven 官方下载地址。可以把 distributionUrl 改成内部 Nexus 或 Artifactory 的 Maven zip 地址，但要保证这个地址长期可用。不要把下载后的 Maven 目录提交进仓库，.mvn/wrapper/dists/ 应该忽略。

Wrapper 还应该和 JDK 版本一起管理。Maven 固定为 3.9.6，但 CI 用 JDK 11、本地用 JDK 17，构建结果仍可能不同。可以在 README、CI 配置、Dockerfile 或 .java-version 中明确 JDK，必要时用 Maven Enforcer Plugin 检查 Java 和 Maven 版本。这样失败会发生在构建早期，而不是编译一半后报出一串难懂的插件错误。

安全方面也不要完全忽略。distributionUrl 指向的是构建工具下载地址，如果被改到不可信源，等于所有构建机器都会执行来路不明的工具链。企业项目可以使用内部制品库代理 Maven distribution，并配合代码评审关注 wrapper 文件变更。升级 Wrapper 时不要只看能不能构建，还要确认下载地址、版本号和脚本内容都符合团队规范。

在多人协作里，README 也要同步改成 Wrapper 命令。文档写 mvn test，CI 写 ./mvnw verify，新人通常会照文档执行，最后又回到工具版本不一致的问题。更好的做法是所有示例命令都用 ./mvnw，Windows 用户旁边补一行 mvnw.cmd，避免靠口头提醒。

如果仓库启用了 Dependabot 或 Renovate，也要把 Wrapper 升级纳入规则。依赖升级只改 POM，工具链升级改 wrapper，两类变更最好分开提交，回滚时才清楚影响范围。 这样 CI 失败时，定位会更快。评审时看到 wrapper 文件变化，不要只看版本号，还要确认 distributionUrl 没被改到临时地址。

追问

Maven Wrapper 和固定 pom 里的插件版本有什么区别？

Wrapper 固定的是 Maven 运行器版本，POM 固定的是项目依赖和插件版本。两者解决的问题不同，不能互相替代。取舍上，小项目只固定插件版本也能跑，但团队协作和 CI 最好连 Maven 本身一起固定。坑在于 Maven 版本升级后传输策略变了，比如旧 HTTP 仓库被拦截，POM 没动但构建突然失败。

maven-wrapper.jar 要不要提交到 Git？

多数团队会提交，这样首次构建不依赖额外下载 wrapper jar，只下载 Maven distribution。也可以不提交 jar，使用下载器模式，但这增加了首次构建的不确定性。取舍点是仓库洁癖和构建稳定性，企业项目通常更偏向稳定。踩坑最多的是只提交 mvnw，没提交 .mvn/wrapper，新人执行脚本时才发现缺文件。

Maven Wrapper 能不能解决依赖下载慢？

不能直接解决。它只保证用哪个 Maven 版本，依赖下载速度仍取决于仓库镜像、网络和缓存。可以配合 settings.xml 的 mirror、CI cache、公司制品仓库来加速。边界要分清：Wrapper 管工具，settings 管仓库；把镜像地址硬塞进 wrapper properties 只能影响 Maven 本体下载，不会影响项目依赖。

什么时候需要升级 Maven Wrapper？

当 Maven 版本存在安全修复、公司统一升级、插件要求更高 Maven 版本，或者旧版本和当前 JDK 不兼容时需要升级。升级命令可以用 ./mvnw -N wrapper:wrapper -Dmaven=3.9.6，然后检查 properties 和脚本变化。取舍是新版本带来修复，也可能带来更严格的校验。常见坑是只改 distributionUrl，没有更新 wrapper 相关脚本，导致不同系统上的行为不一致。

CI 里已经装了 Maven，还需要 Wrapper 吗？

仍然建议用 Wrapper。CI 镜像会升级，托管平台也可能调整预装工具版本，用 Wrapper 可以让构建入口由项目控制。代价是第一次下载 Maven 会多一点时间，但缓存后影响很小。坑在于 CI 脚本一部分用 mvn，一部分用 ./mvnw，排查问题时很难确认到底是哪套 Maven 在执行。

小结

Maven Wrapper 是构建一致性的低成本保险。把 wrapper 文件提交进仓库，本地和 CI 统一使用 ./mvnw，再配合固定 JDK、Maven cache 和公司 settings，构建环境就不会靠口头约定维持。它不解决所有 Maven 问题，但能先把“工具版本不一致”这类噪音降下来。