PyFlink 两件事说清楚就够了

1) FLINK_HOME：决定“用哪套 Flink 发行版”来编译/提交

它影响什么

• PyFlink 在提交前需要用 Flink 发行版做一些编译/打包相关的工作（比如拉起相关脚本、加载依赖、构建 JobGraph 等）。
• PyFlink 的安装包里自带了一套 Flink distribution，默认会用它。
• 你设置了FLINK_HOME后，相当于告诉 PyFlink：别用自带的，用我这套 Flink 发行版。

什么时候一定要设

• 你本机/集群 Flink 版本和 PyFlink 自带版本不一致，出现各种诡异兼容问题
• 你希望明确绑定到公司统一安装的 Flink（比如/opt/flink-2.0.0）
• 你需要使用某些自带发行版里没有的脚本/插件布局（或者你做了定制发行版）

示例（Linux/macOS）

exportFLINK_HOME=/opt/flink-2.2.0

示例（Windows PowerShell）

setx FLINK_HOME"D:\flink-2.2.0"

2) PYFLINK_CLIENT_EXECUTABLE：决定“客户端用哪个 Python”来提交/编译 Python UDF

它影响什么

• 注意是 Client Side：也就是你运行python xxx.py或flink run ...的那台机器。
• PyFlink 在客户端侧需要 Python 来解析你的代码、序列化 UDF、处理依赖等。
• 如果你机器上同时有多个 Python（conda / venv / 系统 Python），这个变量能避免“明明装了依赖却找不到 / Python 版本不对”的坑。

和配置项的关系

它等价于配置项：python.client.executable

并且优先级是（从高到低）：

1. 代码里设置的python.client.executable
2. 环境变量PYFLINK_CLIENT_EXECUTABLE
3. Flink 配置文件里设置的python.client.executable
4. 都没设置就用默认python

示例：指定 conda / venv 的 python

Linux/macOS：

exportPYFLINK_CLIENT_EXECUTABLE=/home/xxx/miniconda3/envs/pyflink/bin/python

Windows PowerShell：

setx PYFLINK_CLIENT_EXECUTABLE"C:\Users\you\.conda\envs\pyflink\python.exe"

一个典型场景（写进博客很有用）

你本地跑脚本时用的是 venv 的 python，依赖都装在 venv 里，但flink run或 IDE 提交时实际用的是系统 python，于是报：

• ModuleNotFoundError
• Python 版本不在 3.9~3.12
• pandas/pyarrow/beam 版本不对

这时候把PYFLINK_CLIENT_EXECUTABLE指向 venv 的 python，问题通常直接消失。

3) 一句话总结（给读者的“最短记忆”）

• FLINK_HOME：选哪套 Flink 发行版（影响编译/提交路径与版本一致性）
• PYFLINK_CLIENT_EXECUTABLE：选客户端用哪个 Python（避免依赖/版本错用）