编写Java Agent时遭遇ClassNotFoundException问题求助

我之前踩过这个一模一样的坑！那个教程确实漏掉了几个关键细节，导致好多人都栽在这里。咱们一步步来排查解决：

1. 先盯紧Agent JAR的打包配置 #

Java Agent的JAR包有两个硬性要求，教程可能没讲透：

• 必须在META-INF/MANIFEST.MF里正确声明入口类：如果是预加载（Premain）方式，要加Premain-Class: com.foo.tracer.Agent；如果是动态Attach方式，要加Agent-Class: com.foo.tracer.Agent。注意必须写全类名，包名不能漏！
• 打包时要包含所有必要的类：别只打Agent这一个类，如果你的插装逻辑还有其他辅助类（比如Transformer实现），必须一起打进JAR里。

给你个标准的MANIFEST.MF模板，直接用就行：

Manifest-Version: 1.0
Premain-Class: com.foo.tracer.Agent
Can-Redefine-Classes: true
Can-Retransform-Classes: true

后面两个配置是可选的，但如果要做类重定义/重转换，加上会避免很多后续问题。

2. 类加载器冲突问题 #

如果是用动态Attach方式加载Agent，Agent类是由系统类加载器加载的。如果你在Agent里引用了不在系统类路径下的依赖类，必然会抛出ClassNotFoundException。解决办法有两个：

• 把依赖库打进Agent的JAR包（也就是打Fat Jar），用Maven的maven-shade-plugin或者Gradle的shadowJar插件都能搞定。
• 启动目标程序时，把Agent的依赖加到系统类路径里（比如用-cp参数）。

3. 检查启动命令的正确性 #

• Premain方式：启动目标程序时的参数要写对，比如java -javaagent:/绝对路径/agent.jar -jar your-app.jar，别用相对路径，尤其是工作目录不确定的时候，很容易找不到Agent JAR。
• 动态Attach方式：调用VirtualMachine.attach(pid).loadAgent(agentPath)时，agentPath必须是Agent JAR的绝对路径，相对路径大概率会失败。

4. 快速排查小技巧 #

• 用jar tf agent.jar命令查看JAR内容，确认com/foo/tracer/Agent.class存在，且MANIFEST.MF里的类名和实际路径一致。
• 启动目标程序时加-verbose:class参数，看类加载日志，能清楚看到JVM尝试加载Agent类时的路径，一眼就能发现路径不对或者类缺失的问题。

我当时就是因为打包时漏了Transformer类，加上MANIFEST.MF里的包名写错了，折腾了快一小时才搞定。按照上面的步骤排查，应该很快能解决你的问题！

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