本文详解如何在 maven 多模块项目中正确集成 web3j-maven-plugin 生成 solidity 合约 java 封装类，并解决因生成源码未被编译器识别导致的 `package does not exist` 编译错误。
在基于 Web3j 构建区块链 Java 应用时，将 .sol 合约自动编译为类型安全的 Java 封装类（Wrappers）是标准实践。然而，许多开发者在多模块 Maven 项目中会遇到一个典型问题：尽管 web3j-maven-plugin 成功生成了 Java 源文件（如 MyContract.java）到 target/generated-sources/web3j/java/ 目录，但后续 mvn compile 阶段却报错：
[ERROR] /src/main/java/org/example/child/TestFile.java:[4,51] package org.example.project-name.wrappers does not exist
根本原因在于：Maven 默认仅将 src/main/java 和 src/test/java 视为编译源路径，而 web3j-maven-plugin 生成的代码位于 target/generated-sources/... 下，该目录未被 Maven 编译器自动纳入源路径（source roots）。这与 OpenAPI 插件等部分工具不同——后者内部可能已通过 build-helper-maven-plugin 或其他机制完成了源路径注册。
✅ 正确解决方案是显式将生成目录注册为附加源路径，推荐使用 build-helper-maven-plugin 的 add-source 目标。以下是完整、可复用的配置步骤：
✅ 步骤一：在子模块 pom.xml 中配置 web3j-maven-plugin（已正确）
确保合约路径、包名和输出目录明确指定（注意：outputDirectory.java 路径需与后续 add-source 路径一致）：
立即学习“Java免费学习笔记（深入）”；
org.web3j web3j-maven-plugin 4.9.4 generate-sources ${project.basedir}/src/main/resources/solidity **/*.sol org.example.project-name.wrappers ${project.build.directory}/generated-sources/web3j/java
✅ 步骤二：在同一子模块 pom.xml 中添加 build-helper-maven-plugin
该插件需在 generate-sources 生命周期阶段执行 add-source，将生成目录注册为有效源路径：
org.codehaus.mojo build-helper-maven-plugin 3.4.0 add-web3j-sources generate-sources add-source ${project.build.directory}/generated-sources/web3j/java
⚠️ 关键注意事项：build-helper-maven-plugin 必须声明在子模块（即实际存放 .sol 文件并需要封装类的模块），而非父 POM；父 POM 中仅可统一管理 版本。 路径必须严格匹配 web3j-maven-plugin 中 的值，否则注册无效。不要遗漏 version（如 3.4.0），避免因默认版本过旧引发兼容性问题。若项目启用 maven-enforcer-plugin，请确保其不强制排除 build-helper-maven-plugin。
✅ 验证与最佳实践
执行以下命令验证全流程是否畅通：
mvn clean generate-sources compile
- generate-sources 阶段：触发 web3j:generate-sources → 生成 Java 类 → 触发 build-helper:add-source → 注册源路径。
- compile 阶段：Maven 编译器将自动扫描 src/main/java 和新增的 target/generated-sources/web3j/java，所有 import org.example.project-name.wrappers.* 均可成功解析。
? 进阶提示：
若需在 IDE（如 IntelliJ IDEA）中实时识别生成类，请在 mvn generate-sources 后执行 "Reload project"（Maven 工具窗口 → 右键项目 → Reload project），IDE 将自动同步新增源路径。
通过以上配置，web3j 生成的合约封装类即可无缝融入标准 Maven 编译生命周期，彻底规避 package does not exist 错误，实现 Solidity 与 Java 工程的高效协同开发。
