本文详解 Maven 插件中如何让命令行 -Dproperty=value 参数真正覆盖 pom.xml 中的 <configuration> 值，并提供可落地的配置模式与最佳实践。
本文详解 maven 插件中如何让命令行 `-dproperty=value` 参数真正覆盖 `pom.xml` 中的 `
在 Maven 构建生命周期中，pom.xml 的 <configuration> 块内硬编码的值具有最高优先级，会直接“屏蔽”命令行传入的 -Dproperty=value 参数——这正是你遇到问题的根本原因。Maven 在解析 POM 阶段即完成属性展开（如 ${project.basedir}），并将 <sourcePath> 和 <outputPath> 解析为具体字符串（例如 C:/Projects/...），随后这些值被固化为 Mojo 实例的最终配置，不再响应外部系统属性。
而命令行参数（如 -DsourcePath=...）仅在以下两种情形生效：
- ✅ <configuration> 中未显式声明该参数（此时 Maven 会尝试通过 @Parameter(property="xxx") 关联的 property 名查找系统属性）；
- ✅ <configuration> 中使用了占位符引用（如 ${sourcePath}），而非直接写死值。
✅ 正确做法：用 POM 属性桥接配置与命令行
应在 pom.xml 中定义可覆盖的属性，并在 <configuration> 中引用它们：
<properties>
<!-- 默认值可设为相对路径或常用位置 -->
<sourcePath>${project.basedir}/src/main/java/com/core/</sourcePath>
<outputPath>C:/Projects</outputPath>
</properties>
<plugin>
<groupId>com.directory.maven.plugins</groupId>
<artifactId>javadoc-generator-maven-plugin</artifactId>
<version>1.2.0-SNAPSHOT</version>
<configuration>
<!-- 关键：此处必须是 ${xxx} 占位符，而非字面量 -->
<sourcePath>${sourcePath}</sourcePath>
<outputPath>${outputPath}</outputPath>
</configuration>
<executions>
<execution>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
</executions>
</plugin>如此配置后，运行以下命令即可成功覆盖：
mvn javadoc-generator:javadoc \ -DsourcePath="C:/Projects/my_project/src/main/java/com/core/" \ -DoutputPath="C:/Projects/tmp"
? 原理说明：Maven 属性解析是分阶段的——先解析 <properties>，再解析 <configuration> 中的 ${...} 引用。当 <configuration> 使用 ${sourcePath} 时，Maven 会在运行时动态查找 sourcePath 属性值：若命令行指定了 -DsourcePath=...，则取其值；否则回退到 <properties> 中定义的默认值。
⚠️ 注意事项与最佳实践
避免混合使用：不要在 <configuration> 中混用字面量和占位符（如 <sourcePath>${project.basedir}/src/main/java/</sourcePath> + -DsourcePath=...），这将导致命令行失效。
插件代码保持简洁：你的 Mojo 中 @Parameter(property = "sourcePath") 已正确声明，无需修改；重点在于 POM 配置方式。
验证是否生效：添加 <debug>true</debug> 到插件配置，或在 execute() 中打印 getLog().debug("Resolved sourcePath: " + sourcePath); 辅助调试。
-
推荐命名规范：为避免与 Maven 内置属性冲突，建议使用带前缀的属性名（如 javadoc.sourcePath），并在 POM 中统一管理：
<properties> <javadoc.sourcePath>${project.basedir}/src/main/java/com/core/</javadoc.sourcePath> <javadoc.outputPath>C:/Projects</javadoc.outputPath> </properties> <!-- ... configuration 中引用 ${javadoc.sourcePath} -->
通过这一模式，你既能为团队提供开箱即用的默认配置，又能保留灵活的 CI/CD 或本地调试覆盖能力，真正实现“约定优于配置”的 Maven 最佳实践。
