最可靠做法是用Dockerfile定制Java运行环境，优先选用openjdk:17-jdk-slim或openjdk:21-jdk-slim镜像，显式设置JAVA_HOME，禁用不稳定的缓存与自动工具安装，并严格锚定JDK及构建工具版本。
CI中用Dockerfile定制Java运行环境最可靠
在CI流水线里硬编码安装JDK、Maven、Gradle等工具，极易因镜像更新或路径变更导致构建失败。直接复用官方openjdk基础镜像并叠加所需工具，是目前最稳定的做法。
- 优先选
openjdk:17-jdk-slim或openjdk:21-jdk-slim，体积小、更新及时、无冗余包 - 避免用
openjdk:17-jdk（基于debian:slim但含更多APT缓存，CI中易触发apt锁冲突） - 若需Maven，用
curl -fsSL https://apache.osuosl.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz解压安装，比apt install maven版本可控、无依赖污染 - 设置
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64（ARM架构则为java-17-openjdk-arm64），CI脚本中必须显式声明，否则mvn可能 fallback 到旧版本
GitHub Actions里复用actions/setup-java要小心版本漂移
该Action虽方便，但默认java-version: '17'不锁定具体patch版本，CI缓存或runner升级后可能拉到17.0.8+7而非原先的17.0.7+7，引发字节码兼容问题（尤其涉及sealed类或record序列化时）。
- 务必写死完整版本号：
java-version: '17.0.7'，并配合distribution: 'temurin'（推荐，比zulu在Windows runner上更稳定） - 禁用
cache: 'maven'除非确认settings.xml未改动——CI中Maven本地仓库缓存常因~/.m2/repository权限或SNAPSHOT时间戳校验失败而静默失效 - 若项目用
gradle wrapper，不要额外跑setup-gradle，wrapper已自带JVM绑定逻辑，多设GRADLE_HOME反而干扰
GitLab CI用image字段指定镜像时，注意ENTRYPOINT覆盖风险
GitLab Runner默认会把.gitlab-ci.yml中的script塞进容器的sh -c执行。但如果自建镜像定义了ENTRYPOINT ["/usr/local/bin/run-java.sh"]，且没正确透传$@，整个script段会被吞掉或执行异常。
- 检查自定义镜像Dockerfile：确保
ENTRYPOINT末尾有exec "$@"，否则mvn clean package根本不会运行 - 更稳妥的方式是弃用
ENTRYPOINT，改用CMD ["jshell"]占位，所有CI命令走script:显式调用 - 若必须用
ENTRYPOINT，在.gitlab-ci.yml中加before_script: []清空默认行为，再手动source /etc/profile.d/jdk.sh加载环境变量
Java 21+在CI中启用--enable-preview需双端对齐
仅在maven-compiler-plugin里配<forcejavaccompileruse>true</forcejavaccompileruse>和<compilerargs>--enable-preview</compilerargs>不够——JVM运行时、测试框架、甚至CI runner自身JDK都得支持预览特性。
立即学习“Java免费学习笔记（深入）”；
- Maven Surefire插件必须≥3.2.5，旧版无法传递
--enable-preview给forked JVM -
mvn test命令行需显式加-DargLine="--enable-preview"，否则JUnit进程仍用默认JVM参数 - GitHub Actions中，
setup-java的java-version必须填'21.0.3'（非'21'），Temurin 21.0.3起才正式支持virtual threads预览特性 - 本地
java --version显示21.0.3-temurin≠ CI中可用，GitLab shared runner可能仍用21.0.1，必须在job开头跑java -version实测
script: - java -version - mvn -B clean compile -Dmaven.compiler.release=21 -Dmaven.compiler.compilerArgs="--enable-preview" - mvn -B test -DargLine="--enable-preview"
CI里Java环境不是“装上就行”，关键在版本锚定、入口控制、预览特性链路贯通。最容易被忽略的是：JVM参数传递是否真正抵达最终执行进程，而不是停在Maven或Gradle wrapper层。
