最常见的原因是路径错误或未下载探针包；需手动下载完整SkyWalking包并解压获取skywalking-agent.jar，使用绝对路径配置-javaagent，注意JDK版本兼容性、插件缺失及ClassLoader干扰问题。
Java应用启动时找不到skywalking-agent.jar
本地挂载探针失败，最常见的原因是路径写错或 jar 包根本没下载。SkyWalking 探针不是 JDK 自带组件，必须手动下载对应版本的 apache-skywalking-apm-bin 压缩包，解压后才能拿到 agent/skywalking-agent.jar。
- 别从 Maven 仓库直接找
skywalking-agent.jar—— 它不单独发布，只随完整包分发 - 确认 Java 应用启动命令里
-javaagent:后面的路径是绝对路径，或相对于启动脚本所在目录的正确相对路径（推荐绝对路径，避免歧义） - Windows 下路径含空格或中文会静默失败，建议把 agent 放到
C:/sw-agent/这类干净路径下 - 如果用 IDE（如 IntelliJ）运行，得在
Run Configuration → VM options里加参数，而不是改 shell 脚本
配置agent.config后服务上报数据但链路不完整
探针加载成功、也能连上 OAP，但 UI 里只有入口 Span，下游 HTTP 调用、DB 查询全没了 —— 这大概率是插件没生效，不是配置文件本身的问题。
-
agent.config中的agent.service_name必须唯一且不含下划线（下划线会被转成连字符，导致服务名归并异常） - 检查
agent/plugins/目录：Spring Web、OkHttp、MySQL JDBC 等插件 jar 是按需加载的，删掉不用的插件不会影响功能，但漏掉关键插件（比如没放mysql-8-plugin.jar却用了 MySQL 8 驱动）就会丢 DB Span - Java Agent 的字节码增强依赖类加载顺序，若应用用了自定义 ClassLoader（如某些老框架或热部署工具），可能绕过探针 —— 可临时加
agent.is_open_debugging_class_transformer=true查日志确认是否增强成功
本地调试时java.lang.instrument.IllegalClassFormatException
这个错误通常出现在用了较新 JDK（如 JDK 17+）但探针版本太旧，或者应用用了 GraalVM、JLink 等定制化运行时环境。
- SkyWalking 9.3.0 开始才正式支持 JDK 17，低于该版本的 agent 在 JDK 17+ 上会抛
IllegalClassFormatException；查清你用的 SkyWalking 服务端版本，下载对应 agent（比如 OAP 是 9.4.0，就用 9.4.0 的 agent） - 若项目用了 Lombok，确保
lombok.jar在 classpath 中位置靠前，否则 agent 可能先尝试增强未脱糖的 AST，触发格式异常 - 禁用特定类增强可临时绕过：在
agent.config加agent.ignore_suffix=.jar,.war或用plugin.springmvc-annotation-class-define类似配置缩小增强范围
IDEA 启动 Spring Boot 时探针不生效
命令行启动没问题，IDEA 里跑却看不到 trace，问题往往出在启动方式和类路径隔离上。
立即学习“Java免费学习笔记（深入）”；
- 不要勾选
Build and run in debug mode下的Enable coverage—— JaCoCo 代理和 SkyWalking 代理冲突，会互相干扰字节码操作 - 确保
Run Configuration → Environment variables里没设置SW_AGENT_COLLECTOR_BACKEND_SERVICES指向错误地址（比如填了localhost:11800但本地 OAP 实际监听127.0.0.1:11800，某些系统 resolve 不一致） - Spring Boot DevTools 默认启用 restart classloader，会导致 agent 初始化一次后被丢弃；加
spring.devtools.restart.enabled=false或把 agent 参数加到Preferences → Build → Compiler → Java Compiler → Additional command line parameters（不推荐，仅临时排查）
真正麻烦的是混合环境：比如本地同时跑多个微服务，共用一个 OAP，但某个服务用了 Netty + 自定义 HTTP 客户端，又没对应插件 —— 这时候链路断点不在配置，而在字节码增强的边界上。得看 agent/logs/skywalking-api.log 里有没有 transform class xxx failed，而不是只盯着 UI 刷不出来。
