企业官网建设流程全解析

“Syntax error, parameterized types are only available if source level is 1.5 or greater”这句话第一次蹦到控制台或者 IDE 的 Problems 面板里时，绝大多数人的第一反应是回头检查尖括号有没有配对、导包有没有写错、泛型参数有没有写反，然后花上半小时确认自己那行List<String> ids = new ArrayList<String>();语法明明毫无问题。问题确实不在代码里，而在于编译器被要求用一套 2002 年前后的语法规则，去读 2004 年之后才进入这门语言的写法。这个报错的本质只有一句话：编译器使用的语言级别（source level）低于 1.5，泛型在它眼里还不是合法语法，于是List<String>中那个<在解析器看来就是出现在了一个不该出现的位置，直接被判定为语法错误，而不是“特性不支持”。

这篇内容面向三类人：一类是刚接手老工程、被一堆<>报错砸懵的新人；一类是在多模块、多构建工具环境里被“改了配置却不生效”折腾过的中级开发；还有一类是要给遗留系统做版本升级、需要一次性把编译配置理顺的负责人。我会把这个报错拆到编译器视角讲清楚它为什么这么报，再把三层容易混淆的版本概念摆开，然后按命令行、Maven、Gradle、IDE 四条路径给出可直接复制的配置，最后把那些“配置明明改了还是报错”的真实现场和长期治理办法一并交代。读完你至少能做到两件事：看到任何一条版本相关的编译错误，三分钟内定位到是哪一层配置没对齐；以及把版本约束固化成工程的一部分，让下一个人不用再踩一遍。

1. 先把报错读明白：这句话到底在抱怨什么

1.1 一句报错暴露了编译器身份

同样一段用了泛型的代码，在不同编译器下报出来的话是不一样的。javac的说法是generics are not supported in -source 1.4 (use -source 5 or higher to enable generics)，措辞直白，明确告诉你“泛型不支持，把 source 抬到 5 以上”。而你看到的这句Syntax error, parameterized types are only available if source level is 1.5 or greater，出自另一套编译器实现（ECJ，也就是很多 IDE 内置的那套 Java 编译器）。这个细节非常值钱，因为它直接决定了你应该去哪儿改配置。

如果你在javac的输出里看到的是“不支持”的口径，那问题基本锁定在构建脚本的命令行参数或构建工具的编译插件上；如果你看到的是“Syntax error”的口径，且报错出现在 IDE 的编辑器红波浪线、Problems 面板里，那八成是 IDE 的项目语言级别、或者 IDE 从构建脚本里推导出来的级别设置有问题。换句话说，报错的措辞本身就是一条线索，它告诉你这口锅该扣给谁。很多人上来就把 pom 改了三遍，结果报错来自 IDE 自己维护的一份项目元数据文件，改一百遍 pom 也没用——后面第 5 章会专门讲这个。

顺带说一句，ECJ 这套编译器不只出现在 IDE 里，一些应用服务器编译 JSP 时、一些嵌入式脚本引擎里、一些历史遗留的插件体系里都可能用它。所以当你在一个完全没有 Java 源码的目录里看到这句报错，先别怀疑人生，去看那个目录下是不是有.jsp、.jspx之类的模板文件，或者有运行期生成源码再编译的逻辑。

1.2 泛型在 1.4 的语法里为什么是“错误”

要理解这个报错，得站在 1.4 时代解析器的立场上想问题。那个年代的语法里，一个类型名后面跟<是没有任何合法解释的：<在那个位置既不能是比较运算符（前面是类型名不是表达式），也不能是泛型起始符（语法里根本没这条规则）。所以解析器扫到List<String>的第一个<，唯一能给出的结论就是“这里不该出现这个符号”。它甚至不知道自己缺的是泛型这个特性，它只知道语法树建不下去了。

这解释了一个很常见的困惑：为什么报错位置常常指向一个看起来完全正常的尖括号，而不是指向 import 或者类声明。因为解析是从左往右、逐 token 推进的，第一次遇到无法归约的符号就停在那里了，后面在 1.4 语法里合法的内容它根本没机会看。所以在 1.4 时代，同样一段逻辑只能这么写：

// 1.4 时代的写法：裸类型 + 强制转换 List ids = new ArrayList(); ids.add("A001"); String first = (String) ids.get(0);

这套写法编译得过，代价是把类型检查从编译期挪到了运行期。如果ids里混进了一个非 String 的对象，编译阶段毫无提示，直到某次线上调用(String) ids.get(0)才抛出类型转换异常。反过来说，泛型的真正价值是把这类错误从运行期提前到编译期，这也是为什么当年整个生态愿意集体升级、而不是继续用裸类型硬扛。理解了这一点，你就不会想着“那我就降级回去用裸类型吧”，因为那是拿工程的长期可维护性换一时的编译通过。

1.3 版本不够会连环报错，别只盯着第一条

泛型只是 Java 5 引入的众多语法特性之一。一旦 source level 卡在 1.4，你会在同一个文件里连续撞上一串报错：增强 for 循环（for (String s : list)）、自动装箱拆箱（Integer i = 5）、变长参数（void f(String... args)）、静态导入、枚举类型、注解——这些统统是 5 才有的。很多人被第一条泛型报错吸引走全部注意力，改完发现下面还有十几条红的，以为是新问题，其实是同一个根因的不同表现。

更麻烦的是这个链条会继续往后延伸。把级别抬到 5 之后，接口方法上加@Override又会报错（那是 6 才允许的）；抬到 6 之后，new HashMap<>()的菱形语法又不行了（7 才有）；抬到 7 之后，lambda 和方法引用又顶上来（8 才有）；再往后还有var（10）、文本块（15）、record（16/17）。所以判断“到底该抬到哪一档”不能拍脑袋，得看你代码里实际用了哪些特性。

下面这张表是我自己在做老项目评估时常用的对照，左边是语法特性，右边是它要求的最低 source level，从下往上扫一遍代码，取最大值就是你的底线：

提示：这张表只用于“确定底线”，不等于“就应该设成底线”。实际项目的 source level 应该跟着团队约定的 JDK 基线走，而不是刚好卡在代码能用最低档位上。

2. 三层版本概念：90% 的人在这一步搞混

2.1 JDK 版本、语言级别、字节码版本不是一回事

这个报错之所以让人头大，是因为“Java 版本”这四个字在日常对话里被滥用了。我习惯把它拆成三层，用写书来打比方会清楚很多：JDK 版本是你手上这套工具和词典的版本（决定你有哪些 API、哪个版本的编译器可执行文件）；**语言级别（source level）**是你被允许使用的写作语法规范（决定你能不能用泛型、lambda 这些句式）；**字节码版本（target level）**是最终印刷出来的成品规格（决定这个 class 文件能被哪个版本的运行时读进去）。

这三者完全可以互相错配，而且错配了不一定立刻报错，这才最坑人。你可以用 JDK 17 的编译器、以 1.4 的语法规范去读代码（就是你现在的状态）、生成 1.4 规格的 class 文件；也可以用 JDK 17 的编译器、以 1.8 的语法规范读代码、生成 1.8 规格的 class 文件，但编译时用的却是 JDK 17 的 API 词典——最后一种能编译通过，运行时却可能在旧环境上抛NoSuchMethodError。第 4 章会专门讲这个陷阱。

理解了这三层，你就明白为什么“我机器上装的是 JDK 17 啊，怎么会报泛型的错”——装了新 JDK 只解决了第一层，编译器完全可以在新 JDK 上被要求按老语法工作。

2.2 三者的组合关系与典型错配

把三层摆开之后，常见的错配组合其实就那么几种。第一种是语言级别低于代码实际用法，也就是本文的主角，症状是语法类报错铺满屏幕；第二种是字节码版本低于语言级别，比如 source 设 8、target 设 7，编译器会直接拒绝，因为 lambda 编译成的指令在旧规格里表达不了；第三种是语言级别和字节码版本都设低了，但 JDK 是新的，这时编译能过、语法也没问题，问题被推迟到运行期；第四种是构建脚本和 IDE 各说各话，脚本里写 17、IDE 里还留着上次导入时的 1.4，于是命令行编译一切正常、IDE 里满屏红。

第三种错配最隐蔽，我见过不止一次：一个模块的source/target都还停在 1.8，但编译机装的是 JDK 17，代码里有人顺手用了新版本才有的 API 方法（字符串处理、集合工厂方法之类），本地和 CI 都绿，一部署到只装了 8 的机器上就起不来。这类问题靠“看报错”是发现不了的，因为压根没有报错，只能靠主动校验，具体手段在第 6 章。

2.3 反推配置源头的通用排查顺序

遇到这句报错，我一般按固定顺序往下走，基本不会绕远路。第一步确认报错来源：是命令行/CI 输出，还是 IDE 面板，措辞是“不支持”还是“语法错误”。第二步确认当前实际生效的配置，注意是“生效”不是“文件里写的”，Maven 用mvn help:effective-pom看合并后的结果，Gradle 用gradle properties或自定义 task 打印，IDE 直接看项目设置面板。第三步顺着继承链往上找：父 pom、公司统一的基础工程、Gradle 的根build.gradle、IDE 的工作区级偏好设置，这些地方的配置会一层层覆盖下来，子模块里没写不代表没设置。第四步全量清理后重建，把增量编译留下的旧产物干掉再验证一次。

这套顺序的价值在于它把“猜”变成了“查”。我踩过的坑里，至少有一半是因为跳过第二步直接改文件——改的是我以为生效的那份配置，实际生效的是另一份。

3. 分场景修复：从命令行到构建工具到 IDE

3.1 纯 javac 命令行：改 -source 与 -target

最朴素的场景，直接调javac编译一批源码。默认情况下，现代 JDK 的javac会按当前 JDK 版本的语言级别工作，不太可能主动降到 1.4；会出现这个报错，通常是因为脚本里显式写了老参数，或者某个批处理文件是从十几年前传下来的。改成下面这样即可：

# 显式指定语言级别与字节码版本，并指定编码避免中文注释乱码 javac -source 1.8 -target 1.8 -encoding UTF-8 -d out $(find src -name "*.java")

如果你用的是 JDK 9 及以上，我更推荐用--release一步到位：

javac --release 8 -encoding UTF-8 -d out $(find src -name "*.java")

--release会同时把语言级别、字节码版本、可用 API 签名三件事都锁到指定版本上，省得你分开填还填不一致。参数怎么选不是拍脑袋，跟着第 1.3 节那张表扫一遍代码，取你实际用到特性的最高档，再和团队的 JDK 基线取交集。这里有个经验：如果这个脚本只是本地临时编译，参数尽量和构建工具保持一致，两套参数并存迟早出分歧。

3.2 Maven 项目：pom.xml 里三个地方都要看

Maven 工程的这个报错，绝大多数来自“没配编译插件，用了插件默认值”。不同版本的编译插件默认值并不一样，早期的默认值落在 1.3 到 1.5 区间，稍新的抬到 1.6、1.8，小版本之间还不统一。所以结论很明确：永远显式声明，不要依赖默认值。配置可以写在属性里，也可以写在插件里，插件里的优先级更高：

<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>17</maven.compiler.release> </properties> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <release>17</release> <encoding>UTF-8</encoding> </configuration> </plugin> </plugins> </build>

如果你的构建环境里插件版本偏老、不支持release参数，那就退回source+target的组合，效果接近但少了 API 签名约束：

<properties> <maven.compiler.source>8</maven.compiler.source> <maven.compiler.target>8</maven.compiler.target> </properties>

改完之后有两个动作不能省。第一，用mvn help:effective-pom确认合并后的结果里确实是你要的值——如果父 pom 里写了另一个值、你的子模块没显式覆盖，看到的可能还是旧值。第二，mvn clean之后再编译，target目录里的旧 class 不清掉，有时候会让你误以为没生效。另外提醒一句，多模块工程里，父 pom 的<properties>会被子模块继承，但子模块自己的<build>配置又会覆盖父级的插件配置，这两条规则叠在一起，就是“我在父 pom 改了怎么没用”的根源。

3.3 Gradle 项目：sourceCompatibility 与 toolchain

Gradle 侧的配置分两种思路。老思路是设兼容性：

// 传统写法：仅声明语法与字节码目标 java { sourceCompatibility = JavaVersion.VERSION_1_8 targetCompatibility = JavaVersion.VERSION_1_8 } tasks.withType(JavaCompile).configureEach { options.encoding = 'UTF-8' }

新思路是用 toolchain，明确指定“用哪个 JDK 编译”，再配release锁定 API 面：

// 推荐写法：JDK 版本、语言级别、API 面三件事分开说清楚 java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } tasks.withType(JavaCompile).configureEach { options.release = 17 options.encoding = 'UTF-8' }

两者的区别值得说清楚：sourceCompatibility只是“允许用什么语法”，编译器还是用当前跑 Gradle 的那个 JDK；toolchain 则是“指定用哪个 JDK 来编译”，即使本机默认 JDK 是别的版本也能编出正确结果。我建议新工程一律用 toolchain，因为它把“编译用哪个 JDK”从环境变量这种容易漂移的东西里解耦出来了。老工程如果 Gradle 版本较老不支持 toolchain，那就先老老实实用sourceCompatibility，把版本抬上去，别为了用新写法先折腾一轮构建工具升级。

还有一个容易忽略的点：sourceCompatibility写在subprojects或allprojects块里，和写在每个模块的build.gradle里，效果是不同的。如果某个模块单独覆盖了，根项目的配置就管不到它。排查时先确认报错模块的实际值，别在根文件上反复改。

3.4 IDE 侧：项目级、模块级、工作区级配置的三重覆盖

IDE 这一层是最容易出“幽灵报错”的地方，因为它自己有独立的元数据文件，和构建脚本是两套。以 Eclipse 系为例，语言级别有三个层级：工作区偏好设置、项目属性里的 Java Compiler 页、以及项目里.settings/org.eclipse.jdt.core.prefs这个文件。三者优先级从低到高，最终生效的是文件里那几个键：

# .settings/org.eclipse.jdt.core.prefs 中的关键三项，缺一不可 org.eclipse.jdt.core.compiler.source=17 org.eclipse.jdt.core.compiler.compliance=17 org.eclipse.jdt.core.compiler.codegen.targetPlatform=17

只改compliance不改source，或者反过来，都会出现“编辑器不报错了但编译还报”“编译过了但字节码版本不对”这类错位现象，所以这三个值必须一起改。如果项目是通过 Maven 导入的，还要注意 Maven 集成插件会按 pom 里的配置重写这个文件，你在界面上改完、下次“更新项目”又被覆盖回去——这种情况就不要在界面上改了，直接去改 pom。

IDEA 侧同样是多层：Project Structure 里的 Project SDK 和 language level、每个 Module 的 language level、Settings 里 Compiler 页的 per-module bytecode version，再加上 Maven 导入时按 pom 推导出来的那一层。.idea/misc.xml里会记录工作区的 JDK 名称和默认语言级别，团队协作时这个文件如果被提交进版本库，很容易出现“别人的配置覆盖了你的”。我的做法是把 IDE 元数据目录整体忽略掉，让每个人本地按 pom 重新导入，构建脚本是唯一事实来源。

改完 IDE 配置后必须做两件事：一是重新导入构建脚本（Maven 的“重新加载项目”、Gradle 的“同步”），二是全量重建。只做第一件不做第二件，增量编译的旧 class 还在，问题依旧。

3.5 老项目从 1.4 往上抬：一次到位还是小步快跑

给十几年前的项目抬语言级别，路线选择上有分歧。小步快跑的做法是 1.4 → 1.5 → 1.6 → 1.7 一档一档抬，每抬一档修一批错误；一次到位的做法是直接定到团队基线（比如 8 或 17），然后集中修一轮。我倾向后者，理由很实际：小步快跑的总工作量并不少，每一档都要重新跑一遍全量编译、跑一遍测试，而且中间档位（比如 6、7）早就没有官方支持了，升到那儿毫无收益。

但一次到位有个前提：得先把“语法层”和“API 层”两类问题分开。语法层的错误改起来机械，加泛型参数、把裸类型补全、把强制转换去掉；API 层的问题更麻烦，比如某个方法在新版本里被移除、行为有变化、或者旧代码依赖了早已不推荐的类。我一般的做法是先把source/target抬到目标版本，让它全量报错，把报错按“语法”和“API”分类计数，语法类的一次性批量修，API 类的单独排期。经验上，语法类的量看着吓人但重复度极高，API 类的量少但每一条都要看语义。

注意：抬语言级别时不要顺手把字节码版本抬得比运行时环境还高。编译产物的 target 必须小于等于生产环境实际运行的 JDK 版本，这个约束比“用最新语法”重要得多。

4. source、target、release 到底怎么填

4.1 source 与 target 分开设置的隐藏风险

source管语法，target管产物规格，两个参数分开设，好处是灵活，坏处是很容易设出一个语义上不自洽的组合。最典型的错误是source设 8、target设 7：语法上允许你写 lambda，但 lambda 需要编译成特定指令，而这些指令在 7 的产物规格里表达不出来，编译器会直接报错拒绝。反过来source设 7、target设 8 是合法的（语法保守、产物新），但没什么意义，白白让代码受限制。

还有一种更隐蔽的自洽错觉：source和target都设 8，编译机装的是 JDK 17。语法层面完全自洽，产物也是 8 规格，看起来完美，但编译器引用的是 JDK 17 的 API 词典，你调用的方法在 8 里可能压根不存在。这个组合能编过，却会在旧运行时上崩。我见过一个工程就这么跑了半年，直到某次部署换了运行环境才爆出来，排查时看代码、看依赖、看配置全都没问题，最后是靠对比 class 文件里的方法引用才定位到。

4.2 --release 为什么更可靠

JDK 9 引入的--release参数，本质上就是把上面那个“自洽错觉”堵死了。它做三件事：限定语言级别为 N、限定产物规格为 N、并且只暴露版本 N 的 API 签名，超出范围的 API 直接编译失败。也就是说，--release 8会在编译期就告诉你“这个方法 8 里没有”，而不是等运行期崩。

从-source 8 -target 8迁移到--release 8基本上是零成本的，唯一要注意的是它依赖 JDK 9 及以上的编译器。如果你的构建环境必须支持在 JDK 8 上编译，那就用不了--release，这时只能靠“注意不要用新 API”这种自觉加上第 6 章的校验手段兜底。构建工具那边，Maven 的编译插件从 3.6 起支持<release>，Gradle 侧用options.release，配置方式和前面给的示例一致。

我的建议很明确：只要编译用的 JDK 是 9 及以上，就用--release，不要再用 source/target 分开设。它省掉的不只是配置项，还有一类排查成本极高的运行期问题。

4.3 常用版本组合对照表

下面这张表是我给不同场景准备的默认配置，可以直接抄，抄之前确认一下你的编译 JDK 版本和运行时 JDK 版本：

验证产物版本有个非常直接的办法：用javap -v看 class 文件的 major version。这个数字和 Java 版本有固定映射，比翻配置文件可靠得多，因为它读的是真正生成出来的字节码：

# 挑一个刚编出来的 class，看 major version 是不是你期望的值 javap -v target/classes/com/example/Demo.class | grep "major version"

5. 那些"配置明明改了还是报错"的疑难现场

5.1 缓存、增量编译与脏产物

这类问题的第一大来源就是脏产物。增量编译的逻辑是“只重编改动过的文件”，而判断“改动”的依据是时间戳和依赖图；当你把语言级别从 1.4 改成 8 的时候，源文件一个都没动，增量编译器很可能认为无事可做，于是旧的、按 1.4 编出来的 class 原封不动躺在那儿，运行或后续编译继续出错。表现出来就是“配置明明是对的，报错还是那句话”。

对应的处理动作要按构建工具区分：Maven 用mvn clean清掉target；Gradle 用gradle clean build --rerun-tasks强制重跑；IDE 侧做全量重建而不是普通构建。Eclipse 系还要额外做一次项目的清理，因为它除了bin目录外还有一套自己的索引和问题标记需要重建。我个人的习惯是每次改动编译级别，都无条件跟一次全量清理，这个动作花不了两分钟，但能省掉半小时的“为什么没生效”。

还有一个更容易忽略的位置：本地仓库里的安装产物。多模块工程里，如果 A 模块依赖 B 模块，而你只重编了 B 没重新安装，A 编译时拿到的可能还是仓库里那份旧的 B。这时候需要把 B 重新安装一遍，或者用多模块一次性构建的方式整体编译。

5.2 多模块工程里被忽略的子模块

多模块的配置继承关系是排查重灾区。父 pom 里设了maven.compiler.source，子模块里如果自己又写了一段编译插件的<configuration>，父级的属性就被插件配置盖过去了；Gradle 的subprojects块对显式覆盖了该属性的模块同样无效；IDE 里每个模块还有独立语言级别。报错往往只出现在某一个模块，而你在父级配置上折腾半天。

判断方法很简单：把报错模块单独拿出来构建，看配置是否还对；对的话说明是汇总构建时的覆盖问题，不对的话说明就是该模块自身配置有漏。另外注意聚合模块和继承模块的区别，<modules>聚合只影响构建顺序，<parent>继承才传递配置，这两者被混为一谈的情况我见过太多了。

5.3 模板、脚本、生成代码里的泛型

有一类报错特别迷惑人：Java 源码目录里干干净净，报错却指向一个.jsp。原因是模板引擎在运行期把模板翻译成 Java 源码再去编译，而这一步用的编译器、用的语言级别是独立配置的，跟你的构建脚本没关系。早期版本的应用服务器的 JSP 编译默认级别有的还停在 1.4 到 1.5 区间，较新的版本抬到了 1.6、1.7、1.8。如果模板的部署描述符版本很老，默认值还会更低。

处理方式是在容器的 JSP 配置里显式指定编译用的语言级别和产物规格（不同的容器参数名不一样，但基本都有“编译源版本”“编译目标版本”这两个开关），或者把部署描述符升级到较新的版本。同样的道理适用于代码生成器：某些老版本生成器吐出来的源码里带裸类型、或者带一些早期语法，如果它生成的代码要和你项目一起编译，就得让生成器的输出和你项目的语言级别对齐。

5.4 第三方源码与反编译代码

把第三方源码直接拷进工程、或者用反编译工具把 jar 反编译成源码再编进项目，是另一个高频现场。反编译出来的代码经常带着大量泛型签名、匿名内部类、合成方法，这些东西在低语言级别下根本编不过。更麻烦的是，你可能只是想让工程“编得过”，于是去找那些报错的文件，结果发现它们在某个第三方包目录下，改了以后和上游对不上。

我的处理原则是：第三方代码不要和业务代码用同一套编译配置混着编。要么把它作为依赖引入二进制包，要么单独建一个模块来承载，那个模块单独使用它需要的语言级别。如果确实必须内联源码，至少把它放在独立的源码目录里，配上独立的编译任务，避免污染主工程的配置。

5.5 问题速查表

把上面这些现场整理成一张速查表，出问题的时候从上往下对：

提示：排查时优先看“实际生效的配置”而不是“文件里写的配置”，前者需要查询命令或界面面板，后者只是你的假设。

6. 把版本约束固定下来：团队与流水线上的长期治理

6.1 构建期强制校验

事后排查再熟练，也不如事前拦住。构建期校验有几件事值得做。第一，在父级配置里单点定义版本，所有子模块继承，禁止子模块自行覆盖，这条靠约定加上代码评审保证。第二，加一条 JDK 版本校验，Maven 侧可以用 enforcer 类插件声明要求的 JDK 版本区间，不满足直接构建失败；Gradle 侧可以写一小段检查任务，读JavaVersion.current()不符合就抛异常。这类校验的价值在于把“环境不对”从运行期问题变成构建期失败。

第三，把--release当成默认选项，只要编译 JDK 支持就一律用它。这一条能消灭掉前面说的那类“能编过但运行崩”的问题，收益远大于配置成本。第四，在构建日志里打印实际版本，把java -version、构建工具版本、生效的语言级别和产物规格统统打出来。CI 上出问题的时候，这份日志能省掉大量来回确认。

# 构建脚本开头加这么一段，日志里一眼能看到实际环境 java -version 2>&1 mvn -v 2>&1 | head -n 3

6.2 配置收敛与文档化

团队规模一旦上去，“每个人本地配置不一样”就是必然。收敛的手段有三层：第一层是构建脚本作为唯一事实来源，IDE 元数据全部忽略，任何人都通过导入构建脚本获得配置；第二层是把编译级别写进项目说明，一句话就行——“本工程语言级别与产物规格均为 17，编译 JDK 不得低于 17”——放在仓库根目录的说明文件里；第三层是用自动化检查兜住，比如在持续集成里跑一次javap检查产物 major version，不符合就失败。

第三层听起来有点小题大做，但它解决了一个真实痛点：配置漂移是渐进的，今天有人加了一个模块没继承父级配置，明天有人手动改了一下 IDE 设置，单看每次都没问题，累积到某次发布就炸。机械化的检查能把这个过程掐断在源头。

6.3 流水线与本地环境的差异

最后说说流水线。本地能编、流水线编不过，最常见的原因是两边默认 JDK 不同。容器镜像里的 JDK 版本、JAVA_HOME指向、构建工具的 daemon 缓存、甚至本地仓库的挂载方式，都可能让同样的命令跑出不同结果。处理办法不是去猜，而是把环境信息打全：构建开始时输出 JDK 版本和构建工具版本，构建结束后输出产物的 major version，两个版本对不上就是环境问题，不用怀疑代码。

还有一个细节：构建工具的守护进程会缓存编译环境，某些情况下切换 JDK 后守护进程还在用旧的。遇到“JDK 明明换了但编译行为没变”，先把守护进程停掉再试。这个坑我在本地和流水线都遇到过，排查时很容易被忽略，因为谁会想到一个常驻进程记着上一次的 JDK 呢。

我自己在这个问题上折腾过好几轮，最后沉淀下来的习惯其实就三条：改任何编译级别相关配置，一定跟一次全量清理；配置只写在构建脚本里，界面上的设置一概不信；每天早上第一条构建命令之前，先撇一眼日志里的 JDK 版本。这三条看着朴素，但它们把“版本类问题”从需要排查半小时的疑难，压缩成了扫一眼就能确认的日常。至于那个List<String>报错本身，它现在已经变成了一个信号——看到它，我就知道该去查配置而不是查代码了。