Java Maven 构建流水线怎么避免本地能过、CI 失败：JDK 矩阵、依赖缓存与质量门禁

周一早上，订单服务在开发机上执行 mvn verify 显示全绿，代码推到 CI 后却卡在测试阶段直接报错：本地跑的是 JDK 21，构建机默认配置还是 JDK 17，再加上依赖缓存规则没做固定，初看失败日志很容易误以为是偶发网络波动。排查这类流水线问题时，先把 JDK 和 Maven 运行环境固定下来，再梳理缓存规则，最后再考虑并行提速，往往比反复点重跑按钮能更快定位根因。

先把“本地能过”拆成四个可验证条件

这次故障的提交完全没改动业务逻辑，真正发生偏移的是构建环境。把成功条件逐一拆解后，流水线至少要能明确回答四个问题：当前用的哪个 JDK，哪个 Maven，依赖包从哪个路径拉取，哪一道检查规则负责拦截坏提交。

这里不用急着给 CI 加更多自动重试规则。重试只能缓解远程仓库短暂抖动的问题，既不能修复 JDK 版本不一致的问题，也不可能让原本失败的用例直接跑绿。

触发器和权限先收窄，构建才不会被误启动

订单服务的流水线拆成两类独立入口：Pull Request 触发时只跑编译、测试和质量检查；代码合并到 main 分支后才正式生成制品。这么做的好处是，普通开发分支不会拿到发布凭据，也不会因为手动点错按钮误上传生产制品。

name: java-ci

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read
  checks: write

jobs:
  verify:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        java: ['17', '21']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: ${{ matrix.java }}
          cache: maven
      - run: ./mvnw -B -ntp verify

示例配置里的权限仅允许读取代码和回写检查结果，真正的发布凭据要放到合并后的独立任务里，再通过环境保护规则限定仅指定来源分支能触发。

JDK 矩阵要和项目编译目标对齐

如果项目的 maven.compiler.release 设定为 17，至少要在 JDK 17 环境上完整验证一次；如果生产环境运行时已经升级到 21，可以额外加 JDK 21 作为兼容性校验项。矩阵不是堆的版本越多越好，两个明确有维护责任的运行时，往往比一串没人管的无效版本价值高得多。

17UTF-8

流水线执行的最开头直接打印版本信息，出问题时能直接确认当前环境，不用再反过来猜 Runner 的默认配置：

java -version
./mvnw -version
./mvnw -B -ntp -DskipTests compile

如果两个 JDK 都能正常编译，但只有一个版本的测试用例失败，问题就从“CI 不稳定”缩小成了运行时兼容性差异。这时候优先排查测试报告、时区配置和文件编码，别直接把失败阶段挪到后台放过。

Maven 依赖缓存只解决等待，不替代版本约束

依赖下载是 CI 流程里最容易被误判的等待节点。缓存命中可以省去分钟级的网络等待耗时，但缓存键必须跟着操作系统、JDK 版本、Maven 配置和依赖描述同步变化，不然旧缓存包会把问题直接藏起来。

- name: Cache Maven repository
  uses: actions/cache@v4
  with:
    path: ~/.m2/repository
    key: maven-${{ runner.os }}-jdk-${{ matrix.java }}-${{ hashFiles('**/pom.xml', '.mvn/wrapper/maven-wrapper.properties') }}
    restore-keys: |
      maven-${{ runner.os }}-jdk-${{ matrix.java }}-

仓库结构变更后第一次构建出现缓存未命中属于正常情况。更需要警惕的是“缓存命中但依赖解析结果不一致”，这类问题通常和未锁定的版本范围、私有仓库镜像变化、构建脚本偷偷修改本地仓库有关。项目里优先用明确写死的版本号，同时引入 Maven Wrapper 统一构建环境。

把测试、质量检查和打包排成一条可回退的流水线

一套实用的执行顺序是：先跑编译，再跑单元测试，接着跑静态检查，最后才执行打包操作。每一步都输出可持久化保存的报告，后续阶段仅在前一步执行成功的前提下才启动。这样失败通知能明确指出是“测试失败”还是“质量检查失败”，也方便把最后一次成功生成的制品作为回退依据。

jobs:
  verify:
    steps:
      - run: ./mvnw -B -ntp test
      - run: ./mvnw -B -ntp checkstyle:check
      - run: ./mvnw -B -ntp package -DskipTests
        if: success()

  publish:
    needs: verify
    if: github.ref == 'refs/heads/main' && success()
    steps:
      - run: ./mvnw -B -ntp deploy

这里的核心不是把所有命令全塞进一个大脚本，而是让每个阶段的边界都能被 CI 平台直接识别到。如果静态检查和测试执行速度都很慢，可以在同个提交上并行运行，但发布任务仍要等待全部门禁校验全部完成。

失败通知要能回答“谁、哪一步、怎么复现”

只发一条“构建失败”的消息，值班同学拿到还要重新点开流水线翻日志。更实用的通知至少要包含提交号、JDK 矩阵值、失败任务标识、首个失败测试用例和完整日志链接。通知里别只贴最后一行摘要，因为 Maven 输出的最后一行往往只是前面异常的笼统概括，没法直接定位根因。

• 依赖下载失败：记录仓库域名、缓存命中状态和重试次数。
• 编译失败：记录 JDK、Maven Wrapper 版本与完整编译错误栈。
• 测试失败：记录测试类名、失败断言详情和测试报告附件。
• 质量门禁失败：记录规则名称、当前分支和是否允许人工复核。

修复完问题先在同一个提交上重跑，确认稳定通过再合并；如果没改任何代码重跑就直接变绿，要把它当成环境或依赖波动问题处理，补充对应排查记录。

常见问题：缓存和重跑什么时候会帮倒忙

为什么本地用 JDK 21 能跑通，CI 上的 JDK 17 却直接失败？

两套运行时对 API 兼容、默认编码和时间处理逻辑的规则可能存在差异。先看流水线打印的 java -version，再确认 maven.compiler.release 和测试矩阵的配置是不是本来就打算支持多版本运行。

Maven 缓存命中后还需要手动删除重建吗？

不用把清缓存当成每次构建的固定步骤。先检查缓存键是否包含 pom.xml 和 Wrapper 配置；只有怀疑缓存文件损坏或者依赖仓库发生切换时，才针对对应单个缓存键做清理。

失败后连续重跑三次都变绿，能直接算通过吗？

不能直接判定为稳定通过。要保留原始失败日志，确认问题根源是网络波动、资源不足还是测试用例本身存在时间依赖，再把可复现的命令写到问题记录里。

测试和静态检查可以并行执行吗？

可以，只要发布任务等待两者都执行成功再往下走就行。并行优化的是整体等待时间，不会改变质量门禁的完整性要求。

给 Java Maven 流水线留一张验收清单

• 提交触发范围只覆盖需要校验的分支，发布任务使用独立的权限配置。
• JDK、Maven Wrapper、编译目标和字符集都有可见的版本输出记录。
• Maven 缓存路径与缓存键规则明确，依赖版本不依赖模糊的范围配置。
• 测试、质量检查、打包和发布有清晰的依赖关系，失败任务不会自动越过门禁。
• 失败通知包含首个错误、运行时矩阵值和复现入口，生成的成功制品可直接用于回退。

当一条流水线能把环境配置、等待逻辑、门禁规则和通知机制都变成可检查的明确证据，“本地能过、CI 失败”就不再是说不清的玄学问题，而是能直接定位到具体阶段的普通工程问题。