maven-source-plugin (opens new window)

maven-source-plugin 是 Apache Maven 的核心插件之一，其核心作用是将项目的源代码和资源文件打包成独立的 JAR 文件，并与主构件（如编译后的 JAR）一同发布到 Maven 仓库或本地存储。以下是具体作用、使用场景及示例说明：

---

一、插件的主要作用

1. 生成源码包
   将项目的主代码（src/main/java）和测试代码（src/test/java）分别打包为 -sources.jar 和 -test-sources.jar 文件。
2. 支持调试与协作
   其他开发者通过 IDE（如 IntelliJ IDEA）可直接从仓库下载源码包，便于调试依赖库或理解实现细节。
3. 增强构件完整性
   在发布项目到远程仓库（如 Nexus）时，源码包作为附加构件，与编译后的 JAR 一同分发，符合 Maven 生态规范。

---

二、典型使用场景及示例

场景 1：调试第三方依赖库

问题：当项目中依赖的第三方库出现异常，需查看其源码定位问题，但本地仓库仅有编译后的 JAR。
解决方案：
在第三方库的 pom.xml 中配置 maven-source-plugin，使其发布时附带源码包。其他项目依赖该库时，IDE 会自动下载源码包供开发者调试。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.3.1</version>
    <executions>
        <execution>
            <id>attach-sources</id>
            <goals><goal>jar-no-fork</goal></goals>
        </execution>
    </executions>
</plugin>

场景 2：发布项目到私有仓库

问题：团队内部需要共享项目源码，但直接传递代码仓库权限存在管理风险。
解决方案：
在构建时通过 mvn deploy 命令自动上传源码包至私有仓库（如 Nexus）。团队成员在 pom.xml 中声明依赖后，可一键获取源码。

mvn clean deploy  # 自动生成并发布源码包

场景 3：多模块项目源码分发

问题：父 POM 中统一配置插件，但子模块未生效。
解决方案：
maven-source-plugin 需在子模块的 pom.xml 中单独配置，而非父 POM。例如，在微服务架构中，每个服务的源码需独立打包。

场景 4：结合文档生成工具

问题：生成 API 文档（如 Javadoc）时需关联源码注释。
解决方案：
将源码包与 maven-javadoc-plugin 结合使用，确保文档工具能正确解析源码中的注释。

---

三、最佳实践

• 版本选择：建议使用较新版本（如 3.3.1）以兼容 Maven 生命周期。
• 绑定生命周期：通常将插件目标（goal）绑定到 package 阶段，确保源码包随主构件一同生成：

  <execution>
      <phase>package</phase>
      <goals><goal>jar-no-fork</goal></goals>
  </execution>
  

• 避免重复打包：使用 jar-no-fork 替代 jar，避免创建新 JVM 进程，提升构建效率。

---

四、与其他插件的对比

与 spring-boot-maven-plugin 不同，maven-source-plugin 不涉及应用打包或运行，仅专注于源码分发。而前者用于构建可执行 Spring Boot JAR（含内嵌容器）。两者可共存于同一项目中，分别处理源码和运行包。