本文介绍如何在 Gradle 项目中下载并关联第三方依赖（如 OkHttp）的源码，使 jdb 调试器支持单步进入（step into）和 list 查看依赖源码，关键在于正确下载源码 JAR 并通过 -sourcepath 告知调试器路径。
本文介绍如何在 gradle 项目中下载并关联第三方依赖（如 okhttp）的源码，使 `jdb` 调试器支持单步进入（step into）和 `list` 查看依赖源码，关键在于正确下载源码 jar 并通过 `-sourcepath` 告知调试器路径。
要让 jdb 调试器能够浏览和单步执行依赖库（例如 com.squareup.okhttp3:okhttp:4.9.0）的源码，Gradle 默认不会自动下载源码——即使你使用了 io.spring.dependency-management 插件，它仅用于统一管理版本与 BOM，并不负责下载源码或 Javadoc。你需要显式触发源码下载，并为 jdb 配置正确的源码路径。
✅ 正确下载依赖源码
Gradle 提供了内置任务 downloadSources（由 Java Plugin 自动注册），但需确保 idea 或 eclipse 插件未覆盖行为。最可靠的方式是手动定义一个下载任务：
// build.gradle
tasks.register('downloadSources', Copy) {
from configurations.compileClasspath.withDependencies { dep ->
dep.artifacts.each { artifact ->
if (artifact.classifier == 'sources') {
fileTree(dir: artifact.file.parent, include: "*.jar").matching {
include "**/*-sources.jar"
}
}
}
}.files.collect { it.file }
into layout.buildDirectory.dir("downloaded-sources")
}
更简洁实用的做法是直接运行 Gradle 的 idea 或 eclipse 任务（即使不使用这些 IDE）——它们会触发源码下载：
./gradlew idea # 或 ./gradlew eclipse
该命令会自动下载所有 implementation 依赖对应的 -sources.jar，并缓存在 Gradle 的本地仓库（如 ~/.gradle/caches/modules-2/files-2.1/...）中。
你也可以用以下命令手动查找已下载的源码路径：
find ~/.gradle/caches -name "*okhttp*sources.jar" | head -n 1 # 示例输出：~/.gradle/caches/modules-2/files-2.1/com.squareup.okhttp3/okhttp/4.9.0/abc123.../okhttp-4.9.0-sources.jar
✅ 启动 jdb 并配置 sourcepath
jdb 不会自动从 classpath 推导源码位置，必须显式指定 -sourcepath。注意：-sourcepath 接收的是源码根目录路径（即解压后的源码文件夹），而非 .jar 文件本身。
因此推荐两步法：
-
解压 sources JAR 到临时目录（jdb 更易识别）：
mkdir -p ./debug-sources unzip -q ~/.gradle/caches/modules-2/files-2.1/com.squareup.okhttp3/okhttp/4.9.0/*/okhttp-4.9.0-sources.jar -d ./debug-sources/
-
启动 jdb，同时包含项目源码与依赖源码路径：
jdb -sourcepath "src/main/java:./debug-sources" -classpath build/classes/java/main:build/libs/*.jar App
? 提示：-sourcepath 是冒号分隔（Linux/macOS）或分号分隔（Windows）的目录列表，确保包含你自己的 src/main/java 和解压后的依赖源码目录。
✅ 验证调试能力
启动 jdb 后，可执行以下命令验证：
> run > stop in okhttp3.OkHttpClient$Builder.build // 设置断点到依赖类方法 > run > list // 应能显示 OkHttp 源码行 > step // 可单步进入依赖内部
若 list 显示 Source not found，请检查：
- -sourcepath 是否拼写正确、路径是否存在；
- 对应的 -sources.jar 确实已下载且非空（部分库可能不发布源码）；
- jdb 加载的是正确版本的 class（避免因 Gradle 缓存导致 class 与源码版本不匹配）。
⚠️ 注意事项
- io.spring.dependency-management 插件不提供源码下载功能，它仅优化依赖版本解析逻辑；
- 使用 IDE（IntelliJ/VS Code + Java Extension）时，源码关联通常自动完成；jdb 属于命令行深度调试场景，需手动配置；
- 若依赖未发布源码（如某些闭源 SDK），则无法获取源码，此时可结合反编译工具（如 jad 或 IDEA 内置 decompiler）辅助阅读；
- 建议将源码解压步骤封装为 Gradle 任务，提升复用性（如 generateDebugSources）。
通过以上配置，你即可在纯命令行环境中，对 OkHttp 等任意开源依赖实现真正的源码级调试——精准定位问题、理解框架设计、高效排查异常。
