本文详解如何在多模块 maven 项目中正确集成 web3j-maven-plugin，通过配合 build-helper-maven-plugin 将 solidity 合约生成的 java 封装类纳入编译源路径，彻底解决 `package does not exist` 编译错误。
在使用 web3j 进行以太坊智能合约 Java 封装开发时，许多开发者会采用 web3j-maven-plugin 自动从 .sol 文件生成类型安全的 Java 包装器（wrappers）。然而，在多模块 Maven 项目中，一个常见且令人困惑的问题是：虽然生成的 Java 类文件已成功输出到 target/generated-sources/web3j/ 目录下，但在后续 compile 阶段却报错 package xxx.wrappers does not exist —— 这表明 Maven 编译器根本未将该路径识别为有效源码目录。
根本原因在于：web3j-maven-plugin 仅负责代码生成，但不会自动将生成路径注册进 Maven 的 project.compileSourceRoots（即编译源根列表）。相比之下，像 openapi-generator-maven-plugin 等插件通常内置了源路径注册逻辑，因此无需额外配置即可被编译器识别；而 web3j 插件则需手动“告知” Maven：“此处也有源码，请一并编译”。
✅ 正确解法是引入 build-helper-maven-plugin，利用其 add-source 目标，在 generate-sources 生命周期阶段将生成目录显式添加为编译源根。
✅ 正确配置步骤（推荐写入子模块 pom.xml）
<build>
<plugins>
<!-- Step 1: web3j 插件 —— 生成 Java 封装类 -->
<plugin>
<groupId>org.web3j</groupId>
<artifactId>web3j-maven-plugin</artifactId>
<version>4.9.4</version>
<executions>
<execution>
<goals>
<goal>generate-sources</goal>
</goals>
</execution>
</executions>
<configuration>
<soliditySourceFiles>
<directory>${project.basedir}/src/main/resources/solidity</directory>
<includes>
<include>**/*.sol</include>
</includes>
</soliditySourceFiles>
<packageName>org.example.project-name.wrappers</packageName>
<outputDirectory>
<java>${project.build.directory}/generated-sources/web3j/java</java>
</outputDirectory>
</configuration>
</plugin>
<!-- Step 2: build-helper 插件 —— 注册生成目录为编译源根 -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<id>add-web3j-sources</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<!-- 注意：此处路径必须与 web3j outputDirectory.java 一致 -->
<source>${project.build.directory}/generated-sources/web3j/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>? 关键细节说明：
立即学习“Java免费学习笔记（深入）”；
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- build-helper-maven-plugin 的 <phase> 必须设为 generate-sources（而非 process-sources 或 compile），确保在 compile 阶段前完成注册；
- <source> 路径需严格匹配 web3j-maven-plugin 中 <outputDirectory><java> 指定的路径；若遗漏 /java 后缀或路径拼写错误，仍将导致导入失败；
- 推荐在具体需要生成合约包装类的子模块中配置（而非父 POM），避免无意义的路径注册；
- 版本建议使用 3.5.0+（兼容 Maven 3.6+ 和 JDK 11+），旧版本可能存在路径解析异常。
✅ 验证是否生效
执行以下命令后检查输出日志：
mvn clean generate-sources compile -X
若配置正确，你会在日志中看到类似：
[DEBUG] Added source directory: /path/to/project/target/generated-sources/web3j/java
且后续 compile 阶段不再报 package does not exist 错误，TestFile.java 中的 import org.example.project-name.wrappers.*; 可正常解析。
⚠️ 常见误区提醒
- ❌ 不要试图用 <pluginManagement> 统一声明但不实际启用 —— build-helper 必须在 <plugins> 中显式声明并绑定 execution；
- ❌ 不要混淆 add-resource 和 add-source：前者用于资源文件（如 *.properties），后者才影响 Java 编译路径；
- ❌ 不要在父 POM 的 <build><plugins> 中全局配置 web3j 插件（除非所有子模块都需生成），否则可能触发空目录扫描或重复执行；
- ✅ 若使用 IDE（如 IntelliJ IDEA），执行 mvn compile 后建议点击 Reload project，确保 IDE 识别新增源路径。
通过以上配置，你将获得一个健壮、可复现、符合 Maven 标准生命周期的 web3j 集成方案——生成即可见、编译即可用，真正实现合约 Java 封装的自动化工程化落地。
