Java版本不匹配导致mvn compile失败，需在setup-java中指定java-version（如'17'）和distribution（推荐temurin），并与pom.xml中maven-compiler-plugin的source/target一致。
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命令里控制流程：
立即学习“Java免费学习笔记（深入）”；
- 想彻底跳过：用
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声明了<modules></modules>，但CI里mvn verify报Project not found，常见原因是工作目录不对或父POM没被识别。
检查这几点：
- 确认
checkout后没手动cd进子目录，所有Maven命令都在仓库根目录执行 - 父POM里
<packaging></packaging>必须是pom，否则Maven不把它当聚合根 - 子模块
pom.xml里<parent></parent>的<relativepath></relativepath>默认是../pom.xml，如果目录结构特殊，得显式写对 - CI里建议用
mvn -B verify（-B非交互模式），避免某些插件因stdin不可用而挂起
最麻烦的其实是settings.xml里自定义仓库或镜像没同步到CI——本地能跑，CI拉不到私有依赖，这种问题藏得深，得单独查mvn help:effective-settings输出。
