创建Maven原型时StringUtils依赖未被打包的问题排查

架构老林

2026-5-7

解决Maven原型中StringUtils依赖未被加载的问题

我来帮你分析一下问题所在，以及对应的解决方案：

问题根源

你遇到的核心问题是：Maven Archetype项目的依赖默认不会被打包到生成的原型Jar中，而当你执行mvn archetype:generate时，Archetype插件需要在运行时访问StringUtils类，但此时该依赖不在插件或原型的classpath里，所以抛出找不到类的错误。

虽然你已经在pluginManagement的maven-archetype-plugin依赖中添加了commons-lang3，但pluginManagement仅做配置管理，不会自动激活插件的依赖配置，同时原型Jar本身也没有包含这个依赖。

解决方案

方案1：确保Archetype插件能加载到依赖

修改你的pom.xml，将maven-archetype-plugin从pluginManagement移到build/plugins节点下，这样插件的依赖会被实际加载：

<build>
  <extensions>
    <extension>
      <groupId>org.apache.maven.archetype</groupId>
      <artifactId>archetype-packaging</artifactId>
      <version>${maven-archetype.version}</version>
    </extension>
  </extensions>
  
  <!-- 保留pluginManagement的配置，但添加plugins节点激活插件 -->
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>${maven-resources-plugin.version}</version>
        <configuration>
          <addDefaultExcludes>false</addDefaultExcludes>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-archetype-plugin</artifactId>
        <version>${maven-archetype.version}</version>
      </plugin>
    </plugins>
  </pluginManagement>

  <!-- 新增plugins节点，激活archetype插件并添加依赖 -->
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-archetype-plugin</artifactId>
      <dependencies>
        <dependency>
          <groupId>org.apache.commons</groupId>
          <artifactId>commons-lang3</artifactId>
          <version>${commons-lang.version}</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

这样配置后，当执行原型生成命令时，Archetype插件会自动加载commons-lang3依赖，就能找到StringUtils类了。

方案2：将依赖打包到原型Jar中（适用于自定义Archetype生成逻辑）

如果你的StringUtils是在自定义的Archetype Java代码（比如扩展ArchetypeGenerator）中使用，需要把依赖打包到原型Jar里，这时候可以用maven-shade-plugin来构建包含依赖的Jar：

<build>
  <!-- 原有配置不变 -->
  <plugins>
    <!-- 添加shade插件 -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>3.4.1</version>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>shade</goal>
          </goals>
          <configuration>
            <artifactSet>
              <includes>
                <include>org.apache.commons:commons-lang3</include>
              </includes>
            </artifactSet>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

执行mvn clean install后，生成的原型Jar会包含commons-lang3的类，这样Archetype插件加载原型时就能直接访问到StringUtils。

方案3：如果是在生成的项目模板中使用StringUtils

如果你是在src/main/resources/archetype-resources下的Groovy脚本（这些脚本会被复制到新生成的项目中）中使用StringUtils，那你需要确保生成的项目的pom.xml模板中包含commons-lang3依赖，而不是在原型项目的pom.xml里配置。

比如在archetype-resources/pom.xml中添加：

<dependencies>
  <dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>${commons-lang.version}</version>
  </dependency>
</dependencies>

验证步骤

执行mvn clean install重新安装原型到本地仓库
运行mvn archetype:generate测试，看是否还会出现找不到StringUtils的错误

内容的提问来源于stack exchange，提问作者Phate