1. 为什么一个看似简单的编译动作值得单独拿出来讲Flink 这个项目在数据工程圈子里基本属于绕不开的存在流批一体的计算框架社区活跃度高版本迭代也快。但很多人第一次从源码层面接触它的时候卡住的地方往往不是算子怎么写、状态怎么管而是最前面那一步——把源码拉下来之后用 Maven 把它编译出来。听起来像是点一下按钮的事实际操作起来从环境准备到依赖下载再到模块裁剪每一步都有让人抓头发的细节。我自己第一次编译 Flink 源码的时候信心满满地敲下命令结果等了四十多分钟最后报了一堆依赖解析失败当时完全不知道从哪里下手。后来反复折腾了几次才慢慢摸清楚这套构建体系的门道。这篇文章就是把这些经验整理出来给准备从源码编译 Flink 的朋友一条相对顺畅的路。需要先明确一点Flink 的源码构建不是一个 Maven 命令搞定那么简单。它是一个多模块的 Maven 工程包含了几十个子模块模块之间有复杂的依赖关系而且不同版本对 JDK、Maven、Scala 的要求都不一样。如果你只是想用 Flink 写作业直接下二进制包就行没必要编译源码。但如果你需要改源码、调试内部逻辑、做二次开发或者想基于特定版本打自己的包那编译这一步就必须迈过去。这篇文章适合几类人一是想深入 Flink 内部机制、需要读源码甚至改源码的开发者二是需要在特定环境下定制 Flink 发行包的团队三是单纯想搞清楚一个大型 Java 项目 Maven 构建体系是怎么组织的人。不管你属于哪一类下面的内容应该都能帮你少走一些弯路。2. 编译之前必须搞清楚的版本对应关系2.1 JDK 版本不是越新越好Flink 不同版本对 JDK 的要求差异很大这是最容易踩的第一个坑。早期 Flink 1.10 之前的版本基本跑在 JDK 8 上1.11 到 1.14 这个区间开始支持 JDK 11但默认还是 JDK 8。到了 Flink 1.15 以后JDK 11 变成了推荐版本JDK 8 虽然还能用但逐渐边缘化。而比较新的 Flink 1.18、1.19 这些版本JDK 17 的支持已经比较完善了。这里的关键问题是如果你用 JDK 17 去编译 Flink 1.13 的源码大概率会在编译期遇到各种模块访问限制的报错因为 JDK 9 之后引入的模块系统对反射和内部 API 的访问做了严格限制。反过来用 JDK 8 去编译新版本 Flink又可能因为源码里用了新语法而直接编译失败。我的建议是先确定你要编译的 Flink 版本然后去查这个版本官方文档里写的Requirements部分那里会明确列出支持的 JDK 版本。不要凭感觉选也不要觉得高版本 JDK 向下兼容就随便用。2.2 Maven 版本和镜像配置Maven 本身的要求相对宽松3.6 以上基本都能用但有几个点需要注意。第一是 Maven 的settings.xml配置默认从中央仓库拉依赖在国内网络环境下会非常慢甚至频繁超时。配置一个可靠的镜像源是必须的这个不用我多说大家应该都有自己习惯的镜像配置。第二是内存配置。Flink 的构建过程比较吃内存尤其是编译到 flink-runtime 这种大模块的时候。Maven 默认的堆内存可能不够用建议在MAVEN_OPTS里把-Xmx调到 2G 以上我一般设成-Xmx3g -XX:MaxMetaspaceSize512m基本不会再出现内存相关的报错。第三是 Maven 的版本和 Flink 构建插件之间的兼容性。Flink 用到了一些 Maven 插件来做 shade、scala 编译等工作某些老版本 Maven 对插件的支持不完整会导致构建过程中出现莫名其妙的错误。用 3.8 以上的版本比较稳妥。2.3 Scala 版本的坑Flink 有一部分代码是用 Scala 写的尤其是早期的版本Scala 代码占比不小。Flink 同时支持 Scala 2.11 和 2.12 两个版本构建的时候需要通过 profile 来指定用哪个。如果你不指定Maven 会用默认的 profile可能不是你想要的版本。这个问题的隐蔽之处在于编译过程可能不会报错但编译出来的包在运行时可能因为 Scala 版本不匹配而出现NoSuchMethodError或者ClassNotFoundException。所以编译之前一定要想清楚你的运行环境用的是哪个 Scala 版本然后在构建命令里显式指定。3. 从拉取源码到第一次成功编译的完整路径3.1 源码获取与分支选择拿到 Flink 源码有两种方式一种是直接下载 release 版本的源码包另一种是从代码仓库 clone 然后切换到对应的 tag 或分支。如果你只是想编译一个稳定版本下载 release 源码包更省事因为 release 包里已经包含了一些生成好的文件省去了部分代码生成的步骤。如果你需要最新的开发版本或者某个特定的修复分支那就得从仓库 clone。clone 的时候建议加上--depth参数做浅克隆Flink 的仓库历史很长完整 clone 下来体积不小浅克隆能省不少时间和磁盘空间。clone 完成之后用git tag看看有哪些版本标签切换到你要编译的那个。这里有个细节Flink 的版本号格式是release-1.xx.y这样的 tag切换的时候注意别切到release-1.xx这种分支上分支上的代码是持续变动的可能包含未完成的改动编译失败的概率更高。3.2 构建命令的参数拆解Flink 官方推荐的构建命令大致长这样mvn clean install -DskipTests -Dfast -Pscala-2.12看起来简单但每个参数都有讲究我逐个拆开说。clean install是标准的 Maven 生命周期clean 清理之前的构建产物install 把构建出来的 jar 安装到本地仓库。这里用 install 而不是 package是因为 Flink 的模块之间有依赖关系install 能保证子模块构建完成后被其他模块正确引用。-DskipTests跳过测试执行。Flink 的测试用例非常多全跑一遍可能要几个小时第一次编译的时候完全没必要跑测试。但注意skipTests只是跳过测试执行测试代码还是会编译的。如果你想连测试代码的编译都跳过用-Dmaven.test.skiptrue这样能进一步加快速度。-Dfast是 Flink 构建体系里自定义的一个属性它会跳过一些耗时的检查比如 checkstyle、spotbugs、rat 检查等。这些检查在正式提交代码的时候很重要但自己编译的时候跳过能省不少时间。-Pscala-2.12指定 Scala 版本 profile。如果你的环境用的是 Scala 2.11就改成-Pscala-2.11。不指定的话默认 profile 可能不符合你的需求。还有一个常用的参数是-T用来开启并行构建。比如-T 1C表示每个 CPU 核心一个线程。Flink 模块多并行构建能显著缩短时间但要注意内存消耗也会相应增加如果机器内存不够并行反而会因为频繁 GC 而变慢。3.3 第一次编译的预期与常见报错第一次编译 Flink做好心理准备时间会比较长。即使跳过了测试和检查在一台配置还行的开发机上完整编译一遍也需要十五到三十分钟取决于网络速度和机器性能。如果依赖需要从头下载时间会更长。常见的报错有这么几类。第一类是依赖下载失败表现为Could not resolve dependencies或者Connection timed out。这种基本就是镜像源的问题换一个稳定的镜像或者检查网络代理配置。第二类是编译错误比如cannot find symbol或者incompatible types。这种通常是 JDK 版本不对导致的回到上一节检查你的 JDK 版本是否匹配。第三类是内存溢出表现为java.lang.OutOfMemoryError或者 Maven 进程直接被杀掉。调大MAVEN_OPTS里的堆内存或者减少并行度。第四类是插件执行失败比如 scala 编译插件报错。这种可能是 Maven 版本和插件版本不兼容升级 Maven 或者单独指定插件版本试试。4. 模块裁剪不是每次都需要编译全部4.1 全量编译的代价Flink 的模块数量很多从 flink-core、flink-runtime 这种核心模块到 flink-connector-kafka、flink-table 这些外围模块全部编译一遍耗时耗力。如果你只是改了某个连接器的代码完全没必要把整个项目重新编译一遍。Maven 的-pl参数可以指定只编译某些模块-am参数表示同时编译这些模块依赖的其他模块。比如你只改了 flink-connector-kafka 的代码可以这样mvn clean install -pl flink-connectors/flink-connector-kafka -am -DskipTests -Dfast这样 Maven 只会编译 kafka 连接器以及它依赖的模块其他不相关的模块直接跳过时间能省下一大半。4.2 哪些模块可以安全跳过有些模块在开发调试阶段是可以跳过的比如文档模块、示例代码模块、以及一些特定平台的集成模块。Flink 的构建体系里有一些 profile 可以控制这些模块是否参与构建具体可以看根目录pom.xml里的 profile 定义。但要注意跳过模块的前提是你清楚模块之间的依赖关系。如果你跳过的模块恰好是你要编译的模块的依赖那构建就会失败。所以用-pl和-am组合的时候Maven 会自动帮你把依赖模块带上这是比较安全的做法。4.3 增量编译的实践Maven 本身对增量编译的支持有限它不像 Gradle 那样有完善的增量构建机制。但实际使用中如果你只是改了一两个文件重新执行mvn install的时候Maven 会跳过那些没有变化的模块因为它们的 jar 已经安装在本地仓库且没有更新。这个行为不是严格意义上的增量编译但在实践中确实能节省时间。不过有个坑如果你改了某个模块的公共 API依赖它的模块不会自动重新编译可能导致运行时出现方法找不到的错误。这种情况下需要手动 clean 一下相关模块或者干脆全量重新编译。5. 编译产物在哪里怎么验证编译成功5.1 产物分布规律Flink 编译完成后各个模块的 jar 包分布在各自的target目录下。比如 flink-core 的 jar 在flink-core/target/flink-core-1.xx.y.jarflink-dist 的发行包在flink-dist/target/flink-1.xx.y-bin/目录下。如果你要的是一个可以直接部署的发行包关注 flink-dist 模块的产物就行。那个flink-1.xx.y-bin目录里的结构和你从官网下载的二进制包是一样的包含 bin、conf、lib、examples 等目录。5.2 验证编译结果的几个手段编译成功不代表产物可用最好做几个验证。第一检查关键 jar 包是否存在且大小合理如果某个 jar 只有几 KB那很可能是编译过程中出了问题只打了一个空壳。第二用java -jar或者flink --version跑一下看看能不能正常输出版本信息。如果是 flink-dist 的产物进入 bin 目录执行./flink --version能正常输出说明基本没问题。第三如果你编译的是特定连接器可以写一个最小的测试作业引用编译出来的 jar跑一下看看能不能正常工作。这一步能发现一些编译期发现不了的运行时问题比如依赖冲突、类加载问题等。5.3 本地仓库的清理反复编译的过程中本地 Maven 仓库里会积累很多 Flink 相关的 jar有时候会出现本地仓库里的旧版本 jar 干扰新构建的情况。如果遇到莫名其妙的依赖问题可以尝试清理本地仓库里对应版本的 Flink 目录然后重新编译。清理的时候注意别把整个本地仓库都删了那样所有依赖都要重新下载。只删org/apache/flink目录下的内容就行。6. 那些让我多花了好几个小时的细节问题6.1 网络代理与镜像的优先级Maven 的镜像配置和代理配置是有优先级的如果两个都配了可能会出现冲突。我遇到过的情况是镜像配的是国内源但代理指向了一个外部地址结果 Maven 先走代理再走镜像反而更慢。后来把代理去掉只用镜像速度就正常了。另外有些镜像源对特定 artifact 的同步不及时会出现中央仓库有但镜像没有的情况。这种时候可以配置多个 mirror或者对特定仓库单独指定 URL。6.2 编码问题导致的编译失败Flink 源码里有不少注释和字符串包含非 ASCII 字符如果构建环境的默认编码不是 UTF-8编译的时候可能出现乱码甚至编译失败。在MAVEN_OPTS里加上-Dfile.encodingUTF-8能避免大部分编码相关的问题。这个问题在 Windows 环境下尤其常见因为 Windows 的默认编码经常是 GBK。如果你在 Windows 上编译 Flink强烈建议显式指定编码。6.3 依赖冲突的排查思路Flink 依赖的第三方库很多版本冲突是常有的事。Maven 的依赖调解机制是最近优先但有时候这个机制的结果不是你想要的。如果编译或运行时报NoSuchMethodError或者ClassNotFoundException大概率是依赖冲突。排查的工具是mvn dependency:tree它能打印出完整的依赖树帮你找到冲突的库。找到之后可以在pom.xml里用exclusion排除掉不需要的版本或者用dependencyManagement统一版本。6.4 磁盘空间这个容易被忽略的因素Flink 完整编译一遍产生的 target 目录加上本地仓库里的依赖占用几个 GB 的磁盘空间是很正常的。如果磁盘空间不足构建过程中会出现各种奇怪的错误比如写入失败、文件截断等。编译之前检查一下磁盘剩余空间留出至少 10GB 的余量比较稳妥。7. 编译完成之后的一些延伸操作编译成功只是第一步后面可能还有打包、部署、调试等操作。如果你要打一个 fat jar 用于提交作业可以用 Flink 提供的 shade 插件配置把作业代码和依赖打在一起。但要注意Flink 自身的依赖不应该打进 fat jar因为集群上已经有这些 jar 了打进去反而会导致冲突。如果你要调试 Flink 内部逻辑可以在 IDE 里导入源码工程配置好 JDK 和 Maven然后直接在源码里打断点。Flink 的 MiniCluster 模式可以在本地启动一个完整的集群非常适合调试。还有一个常见的需求是编译特定版本的 Flink 并发布到内部仓库供团队其他成员使用。这种场景下需要在pom.xml里配置 distributionManagement指定内部仓库的地址然后执行mvn deploy。不过发布之前记得把版本号改成一个内部约定的格式避免和官方版本混淆。我个人在实际操作中的体会是Flink 的 Maven 编译体系虽然复杂但一旦跑通一次后面就顺了。关键是把版本对应关系搞清楚把镜像和内存配置好剩下的就是耐心等待。遇到报错不要慌大部分问题都能从错误信息里找到线索实在不行就去翻构建日志Maven 的-X参数能输出详细的调试信息对排查问题很有帮助。