Maven插件中使用org.apache.maven.plugin.logging.Log#debug()方法无法输出日志，通常是因为误用了-debug（错误）而非正确的-X或--debug参数；本文详解Maven调试日志的启用方式、插件日志API行为及常见误区。
maven插件中使用`org.apache.maven.plugin.logging.log#debug()`方法无法输出日志，通常是因为误用了`-debug`（错误）而非正确的`-x`或`--debug`参数；本文详解maven调试日志的启用方式、插件日志api行为及常见误区。
在 Maven 3.9.1（及所有现代版本）中，并不存在 -debug 这一命令行选项。这是开发者常见的拼写误解。正确启用 DEBUG 级别日志的唯一标准方式是使用：
mvn clean package -X # 或等价写法 mvn clean package --debug
其中 -X（单短横 + X）是 --debug 的简写形式，二者功能完全一致——它们会：
- 启用 Maven 核心的 DEBUG 日志（如插件解析、生命周期执行、依赖解析等）；
- 同时触发插件中通过 Log.debug(...) 输出的日志可见（前提是插件正确调用 getLog().debug("...")）。
⚠️ 注意事项：
- mvn -debug ... 会被 Maven 解析为尝试执行名为 debug 的目标（goal），而非启用调试模式，此时不仅无 DEBUG 日志，还大概率报错 No plugin found for prefix 'debug'；
- -e（即 --errors）仅增强错误堆栈显示，并不会启用 DEBUG 日志，它与 -X 是正交选项，可组合使用（如 mvn -X -e），但 -e 本身不解决 debug 日志缺失问题；
- 插件内必须显式调用 getLog().debug("message") —— info() 和 error() 默认在 INFO 级别下可见，而 debug() 严格依赖 -X 开关控制是否输出，这是 Maven 日志门控机制的设计，而非插件实现缺陷。
✅ 正确示例（插件代码片段）：
public class MyMojo extends AbstractMojo {
@Override
public void execute() throws MojoExecutionException {
getLog().info("This appears with or without -X");
getLog().debug("This appears ONLY when -X is set");
getLog().error("Errors always visible");
}
}
总结：排查 Maven 插件 DEBUG 日志失效，第一步永远是检查命令行参数——请立即替换 -debug 为 -X，并确认未遗漏空格或拼写错误。只要插件基于标准 Log API 实现且 Maven 版本 ≥ 3.0，-X 即可可靠启用全部 DEBUG 级日志输出。
