A Pei在PySpark的诸多报错里，JAVA_GATEWAY_EXITED 对刚入门的人来说几乎是劝退级别的存在——满屏红色堆栈里看不到任何跟业务逻辑有关的线索，网上搜出来的答案又互相矛盾，有人说重装 Java，有人说是内存不够，还有人让你检查防火墙，折腾一下午最后还是没跑起来。这篇文章从底层机制讲清楚它为什么会发生，并给出一个可以照着执行的排查清单。适合刚接触 PySpark 的开发者，也适合隔三差五被这个错误骚扰却又懒得深究的老手。
1. 报错现场还原：JAVA_GATEWAY_EXITED到底在说什么
1.1 完整报错长什么样
先看一个典型的报错输出：
text复制PySparkRuntimeError: [JAVA_GATEWAY_EXITED] Java gateway process exited before sending the driver its port number
大部分人会下意识去搜“PySparkRuntimeError”或者“JAVA_GATEWAY_EXITED”，然后陷入信息的海洋。但如果你冷静下来看这个报错本身，它其实只讲了两件事：
JAVA_GATEWAY_EXITED是错误类型，表示 Java 侧的 gateway 进程退出了。Java gateway process exited before sending the driver its port number是具体描述，翻译成人话就是：PySpark启动 Java 进程后，这个 Java 进程还没把自己的端口号传给 Python 端，就提前死掉了。
这个报错通常出现在你执行这段代码的时候：
python复制from pyspark.sql import SparkSession
spark = SparkSession.builder \
.appName("test") \
.master("local[*]") \
.getOrCreate()
有些人的报错出现在 sc = SparkContext() 这行，本质上是一回事。这个错误还经常出现在换了一台机器、从 Anaconda 换成虚拟环境、或者升级了 Spark 版本之后，所以定位起来特别容易跑偏。
1.2 理解 PySpark 的“双进程”架构
要真正理解这个错误，必须先搞明白 PySpark 的运行机制。很多教程只告诉你“PySpark 是 Spark 的 Python API”，但这句描述太模糊。实际上，PySpark 在你运行一个任务时，是同时存在两个进程的：
- Python 进程：跑你的 Python 代码，负责 DataFrame 的算子操作、UDF 的调度、结果收集等。
- JVM 进程：真正的 Spark 引擎。Spark 的核心是用 Scala 写的，跑在 JVM 上，所以 JVM 进程里运行着 SparkContext、Driver、Executor 这些核心组件。
这两个进程之间怎么通信？靠的是一个叫 Py4J 的桥接库。Py4J 会在 JVM 里启动一个网络服务，监听本机的一个随机端口，然后告诉 Python 进程“你的端口号是 xx”。Python 进程拿到端口号之后，就能通过这个端口把 Python 方法调用转发给 JVM。
所以整个启动链是这样：
text复制Python 代码调用 getOrCreate
-> 启动 JVM
-> JVM 内部创建 SparkContext
-> Py4J 网关在 JVM 内启动，监听端口
-> 把端口号告知 Python 进程
-> Python 连接成功，SparkSession 可用
JAVA_GATEWAY_EXITED 就在第三步前后出现：门还没有完全打开，里面的人已经走了。
这个机制决定了，所有可能导致 JVM 无法启动、无法完成初始化、或者启动后立刻崩溃的原因，最终都表现为同一个错误。这也是它排查起来最头疼的地方，报错并不会告诉你究竟卡在哪一步。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 九成错误的源头：JAVA_HOME与JDK安装
2.1 三步核对JAVA_HOME
根据我从同事、网友和自己的实践中总结的经验，JAVA_GATEWAY_EXITED 至少有九成是 Java 环境变量的问题。如果你还没检查 JAVA_HOME，可以先停下来，按下面的顺序走一遍。
第一步：确认 Java 是否安装。
在终端执行：
bash复制java -version
如果提示找不到命令，那问题就不用排查了，先装 JDK。注意这里推荐直接装 JDK 而不是 JRE，因为 Spark 需要编译和运行 Java/Scala 代码，JRE 是不完整的。
第二步：确认 JAVA_HOME 变量本身。
Linux / macOS 执行：
bash复制echo $JAVA_HOME
Windows 执行：
bat复制echo %JAVA_HOME%
关键点是，JAVA_HOME 必须指向 JDK 的安装根目录，而不是 bin 子目录，也不是 jre 子目录。比如：
- Linux 上正确的值