build-helper-maven-plugin 是 maven 中添加额外源码目录的标准方式，通过 add-source 目标在 generate-sources 阶段注册 src/gen/java 等路径，支持多目录声明、ide 正确识别，且推荐使用 3.3.0+ 版本以兼容高版本 jdk。
在 Maven 项目中，默认只识别 src/main/java 和 src/test/java 作为源码目录。如果需要将其他路径（比如 src/gen/java 或模块化生成的代码目录）也纳入编译范围，build-helper-maven-plugin 是最常用、最稳妥的方式。
添加 build-helper-plugin 插件配置
在项目的 pom.xml 的 <build><plugins></plugins></build> 节点下加入以下配置：
<plugin><groupid>org.codehaus.mojo</groupid><artifactid>build-helper-maven-plugin</artifactid><version>3.5.0</version><executions><execution><id>add-source</id><phase>generate-sources</phase><goals><goal>add-source</goal></goals><configuration><sources><source>src/gen/java</source><source>src/main/extra</source></sources></configuration></execution></executions></plugin>
注意：必须指定执行阶段为 generate-sources，这样才能确保这些额外源码路径在编译前就被 Maven 的生命周期识别；多个路径用 <source></source> 标签逐个声明。
验证是否生效
执行以下命令后检查输出：
mvn compile -X | grep "Sources to be compiled"
或更直接地，在 IDE（如 IntelliJ IDEA）中刷新 Maven 项目，观察新增路径是否被标记为 “Sources”（通常显示为蓝色文件夹）。若未生效，常见原因有：
- 插件版本过低（推荐使用 3.3.0+，旧版对 Java 17+ 支持不佳）
- 未在
<build></build>下配置，而是错放在<pluginmanagement></pluginmanagement>中（后者仅声明不执行） - 路径是相对路径，但写成了绝对路径或拼写错误（如
src/gen/Java大小写不匹配）
配合代码生成工具一起使用（典型场景）
很多项目在 generate-sources 阶段用插件（如 jaxb2-maven-plugin、protobuf-maven-plugin）生成 Java 类，默认输出到 target/generated-sources/xxx。此时建议：
- 先让生成插件把代码写入
target/generated-sources/xxx - 再用
build-helper:add-source把该target子目录加入源码路径 - 避免手动维护
src/gen/java—— 自动生成 + 自动注册更可靠
例如，注册 Protobuf 生成的代码：
<source>${project.build.directory}/generated-sources/protobuf/java</source>
替代方案说明（不推荐用于此需求）
有人尝试用 maven-compiler-plugin 的 <includes></includes> 或修改 sourceDirectory，但这只能影响编译行为，不会让 IDE 正确识别、不支持多源目录、且易与依赖管理冲突。而 build-helper-plugin 是 Maven 官方推荐的“添加源码根目录”标准方式，兼容性好、语义清晰、IDE 支持完善。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
