Flink 源码开发环境搭建指南：使用 IntelliJ IDEA 与 PyCharm 导入 Apache Flink 工程

• 大数据
• 流处理
• 批处理
• 数据工程

本篇技术指南面向计划为 Apache Flink 项目本身贡献代码的开发者，完整讲解如何将 Flink 多模块 Maven 工程导入 IntelliJ IDEA、配置代码格式化（Spotless + google-java-format / scalafmt）、Checkstyle 静态检查、PyFlink 的 Python 开发环境，并梳理常见编译报错的解决方案。读完本文，你将能够在 IDE 中流畅地浏览、编写、格式化与校验 Flink 源码，并跑通本地构建与检查流程。若你只是想编写 Flink 应用程序而非修改 Flink 本身，请直接参考 Java/Scala API 快速上手文档。

提示：当 IDE 中出现任何异常时，请先在命令行用 Maven 验证——mvn clean package -DskipTests——因为问题很可能出在 IDE 自身（Bug 或配置不当），而非 Flink 代码。

准备工作：获取源码并优化 git blame 体验

克隆 Flink 源码仓库

首先从官方源码仓库检出 Flink 源码：

git clone https://github.com/apache/flink.git

克隆完成后，仓库根目录即包含 pom.xml（Maven 父工程定义）、flink-core、flink-runtime、flink-streaming-java、flink-table、flink-python等数十个模块，以及 .git-blame-ignore-revs 等开发辅助文件。

忽略大型重构提交（git blame）

Flink 维护者在.git-blame-ignore-revs中记录了一批大型重构提交的哈希。查看代码变更历史（git blame）时，这些提交会产生大量噪音。可以在 git 与 IDE 中忽略它们：

git config blame.ignoreRevsFile .git-blame-ignore-revs

执行后，git blame会跳过这些重构提交，将注释归因到真正引入代码改动的提交，大幅提升追溯历史时的可读性。

IntelliJ IDEA 完整配置指南

以下指南基于 IntelliJ IDEA 2021.2 编写，其他版本的菜单细节可能略有差异，请务必按步骤准确操作。

导入 Flink 工程

1. 选择 "New" → "Project from Existing Sources"。
2. 选择克隆好的 Flink 仓库根目录。
3. 选择 "Import project from external model"，并选中 "Maven"。
4. 保留默认选项，连续点击 "Next"，直到进入 SDK 配置界面。
5. 若列表中没有 SDK，点击左上角 "+" 新建：选择 "JDK"，指定 JDK 安装目录并点击 "OK"。经验法则：选择与当前激活的 Maven Profile 匹配的 JDK 版本（Flink 通过 Maven Profile 区分 JDK 8 与 JDK 11 编译目标，见下文常见问题）。
6. 继续点击 "Next" 直至导入完成。
7. 打开 "Maven" 面板（或右键工程 → "Maven"），执行 "Generate Sources and Update Folders"；等效命令为mvn clean package -DskipTests。这一步会触发注解处理器与代码生成器，产出编译所需的部分源码。
8. 执行 "Build" → "Build Project" 构建整个工程。

配置 Copyright Profile

Flink 要求每个源文件头部携带 Apache License 声明（仓库内所有文件均如此，例如 tools/maven/checkstyle.xml 与 flink-python/tox.ini 的开头注释）。在 IntelliJ 中可自动化：

1. 打开 "Settings" → "Editor" → "Copyright" → "Copyright Profiles"。
2. 新建 Profile，命名为 "Apache"。
3. 将以下文本粘贴为 license 文本：

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

4. 回到 "Editor" → "Copyright"，为本项目选择 "Apache" 作为默认 Profile。
5. 点击 "Apply" 生效。

安装必需的插件

打开 "Settings" → "Plugins" → "Marketplace"，搜索并安装以下插件（必要时按提示重启 IDE）：

另外还需要安装google-java-format插件，但必须使用特定版本 v1.7.0.6：下载该版本的 ZIP 包后，在 "Settings" → "Plugins" 点击齿轮图标，选择 "Install Plugin from Disk"，定位到 ZIP 文件安装。请务必不要更新此插件——版本不匹配会导致格式化结果与 Flink 的 Spotless 配置不一致。

代码格式化（Code Formatting）

Flink 使用 Spotless（Maven 插件）统一格式化：Java 采用 google-java-format，Scala 采用 scalafmt。这与根 pom.xml 中的 spotless-maven-plugin 配置严格对应：

<plugin> <groupId>com.diffplug.spotless</groupId> <artifactId>spotless-maven-plugin</artifactId> <version>${spotless.version}</version> <configuration> <skip>${spotless.skip}</skip> <java> <googleJavaFormat> <version>1.7</version> <style>AOSP</style> </googleJavaFormat> <!-- \# refers to the static imports --> <importOrder> <order>org.apache.flink,org.apache.flink.shaded,,javax,java,scala,\#</order> </importOrder> <removeUnusedImports /> </java> </configuration> ... </plugin>

可见 Flink 对 Java 代码强制使用google-java-format 1.7 的 AOSP（Android Open Source Project）风格，并按org.apache.flink → org.apache.flink.shaded → 其他 → javax → java → scala → 静态导入的顺序整理 import（\#表示静态导入），同时自动移除未使用的 import。

在 IDE 中推荐启用保存时自动格式化：

1. "Settings" → "Other Settings" → "google-java-format Settings"：勾选启用插件，并将代码风格改为"Android Open Source Project (AOSP) style"。
2. "Settings" → "Editor" → Code Style → Scala：将 "Formatter" 改为"scalafmt"。
3. "Settings" → "Tools" → "Actions on Save"：在 "Formatting Actions" 中勾选 "Optimize imports" 与 "Reformat code"，并从 "Reformat code" 旁的文件类型列表中选择 Java 与 Scala。

对于早期版本的 IntelliJ IDEA（无内置 Actions on Save）：

1. "Settings" → "Other Settings" → "Save Actions"。
2. "General" 下启用保存触发，例如 "Activate save actions on save"。
3. "Formatting Actions" 下勾选 "Optimize imports" 与 "Reformat file"。
4. "File Path Inclusions" 中添加.*\.java与.*\.scala，避免误格式化其他文件类型。

也可以在命令行用 Maven 对整个工程（Java + Scala）一键格式化：

mvn spotless:apply

对应的校验任务spotless-check绑定在 Maven 的validate阶段，也就是说任何一次普通mvn构建都会自动检查格式是否符合规范。

Java Checkstyle 配置

Flink 使用 Checkstyle 强制执行静态编码规范，当前仓库根 pom.xml 中声明的 Checkstyle 版本为9.3（<checkstyle.version>9.3</checkstyle.version>），与 IDE 中应选择的版本一致。

注意：部分模块未被 Checkstyle 覆盖，例如flink-core、flink-optimizer、flink-runtime。即便如此，在这些模块中工作也请尽量遵循 Checkstyle 规则。

在 IntelliJ 中配置 Checkstyle：

1. "Settings" → "Tools" → "Checkstyle"。
2. 将 "Scan Scope" 设为 "Only Java sources (including tests)"。
3. "Checkstyle Version" 选择9.3。
4. "Configuration File" 下点击 "+" 新建配置。
5. "Description" 填 "Flink"。
6. 选择 "Use a local Checkstyle file"，指向克隆仓库中的 tools/maven/checkstyle.xml。
7. 勾选 "Store relative to project location"，点击 "Next"。
8. 配置属性checkstyle.suppressions.file，值为suppressions.xml，点击 "Next"。
9. 点击 "Finish"。
10. 仅保留 "Flink" 作为激活的配置文件，点击 "Apply"。

上述suppressions.xml对应仓库中的 tools/maven/suppressions.xml（另有suppressions-core.xml、suppressions-optimizer.xml、suppressions-runtime.xml等分模块抑制文件）。checkstyle.xml 本身定义了若干基础规则，例如：TODO 注释不得包含用户名（TODO(格式报错）、禁止行尾空白、禁止使用已废弃的Throwables.propagate(、单文件最大行数 3100（FileLength），并支持CHECKSTYLE.OFF/ON注释来局部抑制检查。

接着导入 Java 代码风格方案：

1. "Settings" → "Editor" → "Code Style" → "Java"。
2. 点击 "Scheme" 旁的齿轮图标，选择 "Import Scheme" → "Checkstyle Configuration"。
3. 导航并选择仓库内的 tools/maven/checkstyle.xml。

验证配置是否生效：点击 "View" → "Tool Windows" → "Checkstyle"，在打开的窗口中点击 "Check Module" 按钮，应报告 0 个违规。

PyFlink 的 Python 支持

flink-python模块同时需要 Java SDK 与 Python SDK，而 IntelliJ IDEA 每个模块只支持配置一个 SDK。如果你要长期投入 PyFlink 开发，官方建议把flink-python作为独立工程导入 PyCharm（或单独的 IDEA 窗口）。若只是偶尔处理 PyFlink（例如运行 Python 测试），可按下述方式在 IntelliJ 内配置：

1. 按照官方文档 "Configure a virtual environment" 在 Flink 工程中创建 Virtualenv Python SDK。
2. 在 Project Explorer 中右键flink-python模块 → "Open Module Settings"（或 "Project Structure" → "Modules" 找到该模块）。
3. 将 "Module SDK" 切换为刚创建的 Virtualenv Python SDK。
4. 打开 flink-python/setup.py，按 IntelliJ 提示安装依赖。

完成后可运行flink-python下的 Python 测试来验证环境。

IntelliJ 常见问题排查

invalid flag: --add-exports=java.base/sun.net.util=ALL-UNNAMED

原因：激活了 "java11" Maven Profile，但使用的是较旧的 JDK。解决：打开 "View" → "Tool Windows" → "Maven"，取消勾选 "java11" Profile，然后重新导入工程。

cannot find symbol: symbol: method defineClass(...) location: class sun.misc.Unsafe

原因：使用 JDK 11 编译一个尚不支持 Java 11 的旧版 Flink（<= 1.9）。解决：打开 "Project Structure" → "Project Settings" → "Project"，将 Project SDK 改为 JDK 8。切换回新版本 Flink 时需恢复此设置。

package sun.misc does not exist

原因：使用 JDK 11 且通过--release选项交叉编译到 Java 8——该选项与 Flink 的构建配置不兼容。解决：打开 "Settings" → "Build, Execution, Deployment" → "Compiler" → "Java Compiler"，取消勾选 "Use '--release' option for cross-compilation (Java 9 and later)"。

示例程序抛出 Flink 类的NoClassDefFoundError

原因：Flink 依赖被声明为 "provided" 作用域，运行时不在 classpath 中。解决：在运行配置中勾选 "Include dependencies with 'Provided' scope"，或者编写一个调用示例main()方法的测试类。

Eclipse

Flink 目前不支持也不推荐使用 Eclipse 开发，请改用 IntelliJ IDEA。

PyCharm 开发 PyFlink

若计划投入 PyFlink 开发，官方推荐使用 PyCharm 作为flink-python模块的独立 IDE。以下指南基于 PyCharm 2019.1.3，其他版本可能有细微差异。

导入 flink-python 工程

1. 打开 PyCharm，选择 "File" → "Open"。
2. 选择克隆仓库中的flink-python文件夹作为工程根目录。该目录内含 setup.py、tox.ini、pyflink/源码包与dev/开发辅助脚本。

配置 Python 代码风格检查（Flake8）

Flink 使用 Flake8 约束 Python 编码规范，其配置位于 flink-python/tox.ini 的[flake8]段（tox.ini 同时定义了py38~py311各版本的 Cython 测试环境）。在 PyCharm 中将其接入外部工具：

1. 为 Python 解释器安装 flake8：pip install flake8。
2. PyCharm 中打开 "Settings" → "Tools" → "External Tools"。
3. 点击 "+" 新建外部工具。
4. "Name" 填 "flake8"。
5. "Description" 填 "Code Style Check"。
6. "Program" 填 Python 解释器路径，例如/usr/bin/python。
7. "Arguments" 填-m flake8 --config=tox.ini。
8. "Working Directory" 填$ProjectFileDir$。

验证方式：在 flink-python 工程中右键任意文件或文件夹，运行 "External Tools" → "flake8"，无违规输出即表示配置成功。

小结

一套可用的 Flink 源码开发环境可以归结为四个关键动作：用 Maven 模式导入根工程并执行源码生成；安装固定版本的 google-java-format（AOSP 风格）与 Scala/scalafmt 支持以匹配根 pom.xml 的 Spotless 配置；导入 tools/maven/checkstyle.xml 并关联suppressions.xml以通过静态检查；对 PyFlink 采用独立的 PyCharm + flake8 环境。遇到任何 IDE 疑难杂症时，先回退到命令行mvn clean package -DskipTests与mvn spotless:apply验证，通常能快速定位是工程问题还是 IDE 问题。

• 大数据
• 流处理
• 批处理
• 数据工程