如何在IntelliJ中调试含Shaded类的Java Agent Jar包？

IntelliJ IDEA 调试步骤 #

1. 先保住调试元数据 #

不管用Maven Shade还是Gradle Shadow插件，一定要在构建时保留行号、局部变量这些调试信息，不然后续断点根本没法对应。

• Maven Shade插件配置示例：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.4.1</version>
  <configuration>
    <shadedArtifactAttached>true</shadedArtifactAttached>
    <shadedClassifierName>shaded</shadedClassifierName>
    <transformers>
      <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
        <mainClass>your.agent.MainClass</mainClass>
      </transformer>
    </transformers>
    <!-- 关键：保留调试信息 -->
    <debug>true</debug>
    <keepDebugInfo>true</keepDebugInfo>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
    </execution>
  </executions>
</plugin>

• Gradle Shadow插件配置：

shadowJar {
  mergeServiceFiles()
  preserveFileTimestamps = false
  reproducibleFileOrder = true
  // 开启调试信息保留
  debug = true
}

2. 手动绑定原源码到Shaded类 #

• 启动调试会话（本地带Agent的程序或者远程调试都行），等Shaded类被加载后，直接搜索Shaded后的类名（比如com.shaded.mypackage.MyClass）打开它的反编译文件。
• 点击文件顶部的Attach Sources，选择原项目的源码目录（就是存放com.mypackage.MyClass.java的src/main/java文件夹）。如果自动匹配失败，右键类文件选择Add Source Root，指定原源码路径，手动把原MyClass.java和Shaded后的类关联起来。

3. 强制断点关联（行号不匹配时用） #

如果原源码和Shaded类的行号对不上，直接在原MyClass.java里设置断点，然后打开IntelliJ的断点面板（Run -> View Breakpoints），右键这个断点选择More，在Class filters里填入Shaded后的类全名com.shaded.mypackage.MyClass，强制让原源码的断点绑定到Shaded类上。

其他编辑器的调试建议 #

Eclipse #

• 先确保Shade时保留调试信息，导入原项目和Agent项目。
• 打开远程调试配置，连接目标程序后，找到Shaded类右键选择Attach Source，指定原源码路径。如果包名变化导致匹配失败，去Source Lookup Path中添加原源码，手动设置路径映射。

VS Code（搭配Java Extension Pack） #

• 安装Debugger for Java插件，在launch.json中添加远程调试配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Remote Debug Agent",
      "request": "attach",
      "hostName": "localhost",
      "port": 5005,
      "sourcePaths": ["/绝对路径/到/原项目/src/main/java"]
    }
  ]
}

• 启动调试后，如果VS Code未自动映射源码，去调试面板的Loaded Classes里找到Shaded类，右键选择Edit Source Lookup添加原源码路径。

额外踩坑提示 #

• 要是行号还是不对，检查是否开启了代码混淆（比如ProGuard），如果开了要么关闭混淆，要么保留混淆的映射文件，让IDE能对应上代码位置。
• 使用Shade插件的Relocate规则时，可以生成映射文件（比如Maven Shade的outputMappingFile参数），导入IDE后能自动匹配原类和Shaded类，省去不少手动操作。

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