很多人一提到“用IDEA编译Spring源码”就觉得难觉得又要下载源码、又要配Gradle、还要处理各种依赖还没开始就放弃了。但如果把整个过程拆开看真正涉及的环节其实不多选对版本、配好镜像、预编译一个关键模块、导入IDEA、再建一个能跑起来的小Demo。这套流程我前前后后折腾过好几遍踩过不少坑也摸到了一些规律。这篇文章我想用比较直接的方式把从零开始编译Spring Framework源码以及把调试环境搭起来的完整过程写清楚核心思路就一个全程可复现每一步都知道为什么这么做。不管你是准备Spring面试想搞懂三级缓存还是想研究IoC容器内部结构这套环境搭完之后你都能直接在源码上打断点观察容器启动过程中的真实调用链。这篇内容适合两类人一类是刚开始啃Spring源码、还不知道怎么把工程跑起来的初学者另一类是已经能跑Spring Boot、但一直没真正打开过Spring Framework源码工程的老同学。1. 编译前准备JDK、Gradle与源码版本怎么搭才不折腾1.1 为什么版本搭配比操作步骤更重要编译Spring源码这件事最先卡住人的往往不是代码问题而是版本问题。Spring源码的构建系统是Gradle而Gradle对JDK版本非常敏感。拿Spring Framework 5.3.x来说它的Java基线虽然写着JDK 8但实际在JDK 11下编译最稳JDK 8也能跑到了JDK 17则有可能触发Kotlin插件和Groovy插件的兼容性问题。如果你选择的是Spring 6.x那就必须用JDK 17起步因为Spring 6本身基线就是17。另一个关键点源码里自带的gradle/wrapper/gradle-wrapper.properties已经锁定了Gradle版本所以你不需要自己另外安装Gradle直接用wrapper就能拉取对应版本。但问题也出在这官方下载地址在国内经常慢到怀疑人生。我第一次编译时光下载Gradle发行包就挂了三次最后换成国内镜像才顺利走完。所以版本选型、发行版镜像、依赖仓库镜像这三件事一定要在动手之前想清楚。1.2 环境检查清单与版本对应关系为了让你少走弯路我把经过验证的版本搭配整理成了表直接照抄就行项目推荐版本说明JDK11编译Spring 5.3.x如果编译Spring 6.x则用JDK 17IDEA2023.2或更新版本新版对Gradle 7.x支持更完整Spring源码5.3.x最新tag覆盖面试大部分问题依赖兼容性好Gradle由源码内wrapper决定命令行和IDEA使用同一份缓存先检查一下本机当前的Java版本java -version如果机器上装了多个JDK不用卸载任何一个IDEA里可以单独指定Gradle JVM路径。打开Settings - Build, Execution, Deployment - Build Tools - Gradle把Gradle JVM切到JDK 11就好。没有的话点Add JDK手动选择Home目录。1.3 源码目录最好不要放在中文路径下这一点非常容易被忽略。Spring构建过程中会执行很多脚本和代码生成任务一旦项目路径里出现中文或者空格个别任务会莫名报诡异错误比如Unrecognized option或者Path contains invalid characters。我习惯把源码放在一个纯英文路径下比如D:/code/spring-framework后面基本没遇到过因为路径引起的幺蛾子。2. 源码下载与构建加速先解决Gradle的“慢”问题2.1 获取Spring源码的方式和注意事项源码获取有两种方式一种是GitHub页面直接下载zip另一种是git clone然后切tag。我更推荐clone因为后面想切换版本时非常方便。git clone https://github.com/spring-projects/spring-framework.git cd spring-framework git checkout v5.3.39Windows用户注意如果clone时报Filename too long先执行一条命令git config --global core.longpaths trueSpring项目文件名普遍偏长不设置这个后面容易报错。下载zip也不是不行但zip没有.git目录Spring构建脚本里有一部分任务需要读取git信息生成版本号保留.git目录会省去很多烦恼。2.2 替换Gradle发行版下载源打开源码根目录下的gradle/wrapper/gradle-wrapper.properties你会看到类似这样的内容distributionUrlhttps\://services.gradle.org/distributions/gradle-7.5-bin.zip把发行版地址换成国内镜像比如腾讯镜像distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-7.5-bin.zip这里解释一下原因Gradle发行包大约100多MB从官方地址下载在国内经常超时。换了腾讯镜像之后基本能跑满带宽。这一步只是替换Gradle本身的下载地址和后面的Maven依赖仓库镜像是两回事很多人混在一起结果只配了一个下载还是龟速。2.3 init.gradle仓库镜像配置Spring源码依赖了大量第三方库包括Kotlin插件、Groovy插件、spring插件等默认从repo1.maven.org拉取速度不稳定。推荐的方案是在~/.gradle/init.d/目录下新建一个init.gradle文件全局生效不需要改动Spring源码本身的任何构建文件。allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/spring } mavenCentral() } buildscript { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/spring } mavenCentral() } } }注意mavenCentral()要放在最后阿里云镜像里没有的依赖才会回源到中央仓库。这样配置之后Gradle解析依赖的速度会有质的提升尤其是首次全量构建时能省下一大截下载时间。3. 命令行编译Spring源码从预编译spring-oxm到全量构建3.1 预编译spring-oxm不理解就会一直踩坑直接跑./gradlew build经常会遇到报错提示找不到org.springframework.oxm相关类比如Could not find org.springframework:spring-oxm:5.3.39。这个问题的根源在于Spring源码的构建体系里spring-core模块的一部分代码生成任务依赖spring-oxm模块先完成编译。如果你一上来就全量构建task执行顺序乱了就会报类找不到。按官方贡献文档和社区里的通用做法需要先单独编译spring-oxm模块./gradlew :spring-oxm:compileJava这一步的作用是把oxm模块的class生成到build目录下后续其他模块编译时才能引用到。不要偷懒跳过它在整个流程里的地位相当于打地基。3.2 全量构建命令及各参数说明编译完oxm之后开始全量构建./gradlew build -x test-x test表示跳过单元测试。Spring官方测试集非常庞大跑一遍完整测试可能半小时起步对于只想搭建源码阅读环境的人来说完全不划算。跳过测试并不会影响源码本身的编译质量。如果遇到spring-aspects模块报AspectJ编译错误通常是JDK版本和AspectJ插件不兼容导致的可以追加排除./gradlew build -x test -x :spring-aspects:compileJava但我不建议一开始就排除先用完整命令跑遇到具体问题再针对性处理。这里有一个容易犯的错看到报错后习惯性执行clean再重来结果把前面预编译的oxm产物也删了导致同样的错误又出现。如果你真的需要clean执行完之后记得重新跑一遍:spring-oxm:compileJava。3.3 快速验证编译结果构建结束后可以去spring-core/build/libs目录下看有没有生成Spring的jar包。但如果只看到jar还不能百分百确认IoC相关的模块都没问题。我更推荐的方式是直接用下面第5节里的Demo工程跑一次只要Spring容器能正常启动说明整个编译链路就是通的。如果你只想编译部分模块也有更省时的做法./gradlew :spring-beans:compileJava :spring-context:compileJava但是对于初学者我还是建议全量编译一次。因为IDEA打开整个Spring工程后各个子模块之间会互相引用只编译部分模块的话IDE里会到处报红影响阅读体验。4. IDEA导入Spring工程与编译配置从同步到Build4.1 IDEA中的Gradle全局配置命令行编译只是第一步真正要方便调试还得让IDEA和Gradle协作起来。打开IDEA后先进Settings - Build, Execution, Deployment - Build Tools - Gradle把Gradle user home指向~/.gradle之前配置的init.gradle就在这个目录下IDEA同步时会自动读取。Gradle JVM按照第1节的版本对应表选择编译Spring 5.3.x建议选JDK 11。还有一个容易被忽视的选项Build and run using保持Gradle不要改成IntelliJ IDEA。虽然IDEA自带的编译速度更快但Spring源码里有大量Gradle插件生成的代码用IDEA自己的Builder跑容易漏掉这些生成步骤最终导致运行时缺类。4.2 导入项目并完成首次同步选择File - Open定位到源码根目录选中build.gradle文件IDEA会自动识别这是一个Gradle项目。这里有个小技巧选的时候可以直接选build.gradle不要只选目录这样可以减少一次手动关联。首次同步的时间取决于网络和机器配置正常情况下10到20分钟。如果超过30分钟还在转圈多半是某个依赖下载卡住了。这时候打开View - Tool Windows - Gradle查看具体的下载任务确认是不是卡在某个仓库上然后回头检查init.gradle的镜像配置。同步完成后IDEA的Project视图里应该能看到一长串Spring子模块spring-core、spring-beans、spring-context、spring-aop等。每个模块都有独立的build.gradle整个工程结构非常清晰。4.3 IDEA环境下编译Spring源码的推荐做法在IDEA里编译Spring源码推荐走Gradle工具窗口而不是直接按右侧的Build按钮。展开spring-framework - Tasks - build双击build任务即可。Gradle工具窗口里能看到每个子任务的执行情况哪一步出错一目了然。如果你只是想快速编译供调试用双击compileJava任务就够了它只会执行Java编译不会触发测试和打包速度会快很多。但注意如果其他模块还没编译过compileJava可能因为缺依赖报错所以这里稳妥起见还是执行build -x test。这里还有一个细节IDEA首次导入时可能因为工程太大而报内存不足。默认的堆内存可能撑不住这么大的项目索引。解决办法是在Help - Change Memory Settings里把IDEA堆内存调到2048M以上甚至4096M然后重启IDEA。5. 搭建可调试的演示工程断点打到Spring容器内部5.1 创建独立调试工程并关联源码模块编译成功之后真正的乐趣才开始。我不建议直接往Spring源码工程里塞业务代码那样会污染源码结构。更干净的做法是新建一个独立的Java模块只用来写测试代码然后通过IDEA的模块依赖关联Spring源码模块。步骤如下File - Project Structure - Modules点加号新建一个普通的Java模块名字就叫debug-demo。在debug-demo的Dependencies里点加号 -Module Dependency选择spring-context、spring-beans、spring-core、spring-expression、spring-aop这些源码模块。把Language level保持在8或者11不要高于当前Gradle JVM的版本。这样操作之后debug-demo里的代码可以直接使用Spring的注解和类而且调试时断点能命中源码模块里的真实源码文件。5.2 写一个能触发IoC容器启动的最小Demo在debug-demo模块里建一个DebugMain类package debug; import org.springframework.context.annotation.AnnotationConfigApplicationContext; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; Configuration ComponentScan(debug) public class DebugMain { public static void main(String[] args) { AnnotationConfigApplicationContext ctx new AnnotationConfigApplicationContext(DebugMain.class); UserService userService ctx.getBean(UserService.class); userService.printName(); ctx.close(); } }再建一个UserService类package debug; import org.springframework.stereotype.Component; Component public class UserService { private String name debug-spring; public void printName() { System.out.println(name); } }先在AbstractApplicationContext.refresh()方法第一行打一个断点然后右键Debug运行DebugMain。如果断点正常命中说明源码编译、模块依赖、调试环境全部打通了。refresh()是整个IoC容器启动的入口后续所有BeanFactory准备工作、BeanPostProcessor注册、单例实例化都是由它驱动的。从这行开始你可以一路Step Into把容器启动的全过程看个遍。5.3 面试经典三级缓存循环依赖断点怎么打这一步是很多同学最想知道的内容因为Spring面试里循环依赖几乎是必问。三级缓存的原理看十遍博客都不如自己打断点走一遍来得直观。先构造一个循环依赖场景。创建两个类互相字段注入package debug; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; Component public class AService { Autowired private BService bService; }package debug; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; Component public class BService { Autowired private AService aService; }把DebugMain的main方法改成获取AServicepublic static void main(String[] args) { AnnotationConfigApplicationContext ctx new AnnotationConfigApplicationContext(DebugMain.class); AService aService ctx.getBean(AService.class); System.out.println(aService); ctx.close(); }然后打开DefaultSingletonBeanRegistry类在getSingleton(String beanName, boolean allowEarlyReference)方法第一行打断点。为了减少干扰给断点加一个条件beanName.equals(aService) || beanName.equals(bService)。启动Debug后观察Variables窗口里的三个关键MapsingletonObjects一级缓存存储完整创建好的单例BeanearlySingletonObjects二级缓存存储提前暴露的早期Bean引用singletonFactories三级缓存存储Bean的对象工厂真正的执行顺序是这样的创建aService时先实例化出原始对象然后把一个ObjectFactory放进三级缓存接着填充属性bService发现bService还没创建于是转去创建bService。创建bService时填充属性aService再次调用getSingleton(aService, true)这时一级缓存和二级缓存都没找到但在三级缓存里找到了aService的对象工厂通过工厂拿到早期引用放入二级缓存同时移除三级缓存中的记录。然后把这个早期引用注入给bServicebService完成创建并放入一级缓存。最后回到aService完成剩余属性填充也存入一级缓存。这个流程走完你对三级缓存的印象就不再是死记硬背了而是真正理解Spring为什么能解决setter注入和字段注入的循环依赖以及构造器注入为什么解决不了。5.4 IDEA断点调试增强技巧调试Spring源码时有几个IDEA的断点技巧非常有用。第一个是条件断点。像上面那样给断点加beanName.equals(xxx)条件可以只命中特定Bean的调用避免被其他Bean的创建过程刷屏。第二个是Evaluate Expression。调试时按AltF8在弹窗里输入表达式比如this.singletonFactories.keySet()可以直接查看当前缓存里有哪几个Bean在等待创建。这个操作在分析容器状态时非常高效。第三个是Set Value。在Variables窗口选中某个变量直接改值可以用来模拟异常场景。比如把某个缓存值强行改成null观察后续代码会不会走到你预期的分支。还有一个细节默认情况下IDEA的Stepping - Do not step into the classes过滤列表会跳过一部分类如果你发现Step Into时进了java.*或者一些代理类而不是Spring的源码类可以打开这个设置检查一下过滤列表保证Spring的类不被跳过。6. Spring源码编译常见报错速查与避坑心得6.1 报错速查表下面这些报错是我在编译过程中实际遇到过的也是社区里出现频率很高的几个整理成表格方便快速定位报错现象原因解决办法Could not resolve org.springframework:spring-oxm缺少JAXB生成类先执行./gradlew :spring-oxm:compileJava下载gradle-7.x-bin.zip超时官方发行版地址慢修改distributionUrl为腾讯镜像Unknown Kotlin JVM target: 17Kotlin插件版本过低编译Spring 5.3.x时使用JDK 11spring-aspects模块AspectJ编译报错AspectJ插件与JDK不兼容追加-x :spring-aspects:compileJavaIDEA运行测试类报Invalid source release: 17模块Language Level与JDK不匹配Project Structure里把Level改成11Process command git finished with non-zero exit value构建试图读取git信息使用git clone而不是下载zipGradle同步时IDEA内存溢出工程太大Help - Change Memory Settings调大堆内存6.2 分享几个容易被忽略的细节再补几个我自己踩过的坑。第一不要在源码目录下跑mvn或者混合使用不同构建工具。Spring源码只认Gradle尤其是它内部的构建脚本耦合了很多自定义任务混用工具会导致各种难以排查的task执行顺序问题。第二如果IDEA的Gradle窗口一直显示Unlinked Gradle project右键项目根目录选择Link Gradle Project重新关联一次就好。第三内存参数建议写到用户级配置里。在~/.gradle/gradle.properties下加一行org.gradle.jvmargs-Xmx4g这样能避免源码目录里的gradle.properties被改动防止将来commit时误提交修改过的构建配置。第四调试Spring源码时spring-beans和spring-context这两个模块的classes目录必须真实存在。如果你只编译了spring-core其他模块还没编译断点仍然命中不了。所以最稳妥的方式还是先执行一次完整的build -x test把整个工程的classes都生成完整再开始调试。最后说点个人体会。编译Spring源码这件事看起来是环境搭建实际是熟悉Spring构建体系和模块关系的捷径。我第一次编译的时候被oxm卡了很久后来才明白是task顺序问题。真正把环境搭好之后我特别喜欢干的一件事就是在refresh()里一路单步看BeanFactoryPostProcessor、BeanPostProcessor分别在哪个时机执行这是看多少文章都换不来的直观感受。另外编译成功后先不要急着跑复杂项目就从一个AnnotationConfigApplicationContext启动开始把spring-core、spring-beans、spring-context这三个模块里的关键类都打上断点走一遍再回头去理解三级缓存和AOP你会觉得整个Spring突然变得“透明”了。这套流程搭建起来之后后面再读源码收获完全不一样。