GitHub配置Java工作流：自动编译测试教程

本文深入解析了在GitHub Actions中配置Java工作流时最常踩的四大坑：JDK版本与Maven编译插件不一致导致的编译失败、测试跳过参数混淆引发的CI卡顿、Maven本地仓库缓存失效拖慢构建速度，以及多模块项目因路径或POM配置错误导致的构建识别失败；通过精准指定setup-java参数、合理选用跳过策略、严格校验缓存Key与路径、规范多模块结构及排查settings.xml同步问题，帮你一次性打通Java项目CI/CD的任督二脉，让每次推送都稳定、快速、零意外。

Java版本不匹配导致mvn compile失败

GitHub Actions默认Ubuntu运行器自带OpenJDK 11，但你的项目可能用的是JDK 17或JDK 21——不显式声明就会编译报错，比如Unsupported class file major version 61（JDK 17对应61）或error: invalid target release: 21。

必须在setup-java步骤中指定java-version和distribution，且要和pom.xml里maven-compiler-plugin的source/target一致：

• java-version填字符串，如'17'或'21'（加引号，否则YAML解析为数字）
• distribution建议用temurin（官方推荐，兼容性好），别用zulu除非有明确需求
• 如果项目用了record、sealed等新特性，光配JDK不够，还得确认maven-compiler-plugin版本≥3.10.1

跳过测试时mvn test仍执行

很多人写mvn compile -Dmaven.test.skip=true想跳过测试编译和执行，结果CI还是卡在test阶段——因为-Dmaven.test.skip=true只跳过测试执行，不跳过编译；而-DskipTests才真正跳过执行，但测试类仍会被编译。

更干净的做法是直接在run命令里控制流程：

• 想彻底跳过：用mvn compile -Dmaven.test.skip=true
• 只想跳执行、保留编译（方便后续调试）：用mvn compile -DskipTests
• CI里通常建议用-Dmaven.test.skip=true，避免因测试依赖缺失导致编译失败
• 注意：Maven 3.9+开始，-Dmaven.test.skip=true已默认禁用测试类编译，无需额外配置

缓存.m2/repository没生效

每次跑都重下几百MB依赖，CI耗时翻倍。问题常出在缓存key写错或路径没对齐。

关键点只有三个：

• 缓存key必须包含setup-java的java-version和distribution，例如：ubuntu-${{ runner.os }}-m2-${{ matrix.java }}-${{ hashFiles('**/pom.xml') }}
• path必须写绝对路径/home/runner/.m2/repository，不能写~/.m2/repository（tilde不展开）
• 确保setup-java在cache步骤之前，否则缓存读取时JDK还没装好

多模块项目mvn verify找不到子模块

根pom.xml声明了，但CI里mvn verify报Project not found，常见原因是工作目录不对或父POM没被识别。

检查这几点：

• 确认checkout后没手动cd进子目录，所有Maven命令都在仓库根目录执行
• 父POM里必须是pom，否则Maven不把它当聚合根
• 子模块pom.xml里的默认是../pom.xml，如果目录结构特殊，得显式写对
• CI里建议用mvn -B verify（-B非交互模式），避免某些插件因stdin不可用而挂起

最麻烦的其实是settings.xml里自定义仓库或镜像没同步到CI——本地能跑，CI拉不到私有依赖，这种问题藏得深，得单独查mvn help:effective-settings输出。

到这里，我们也就讲完了《GitHub配置Java工作流：自动编译测试教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！