如何在Windows 11上配置Spark结构化流的本地检查点目录？

问题核心 #

你遇到的报错根源是：Spark默认采用HDFS作为文件系统，当传入Windows风格的本地路径时，会被错误拼接成hdfs://localhost:9000/C:/...这种非法HDFS路径——HDFS不支持盘符格式的路径命名，因此触发IllegalArgumentException。即使注释了手动设置检查点的代码，Spark自动生成的临时检查点也会沿用默认HDFS规则，导致同样报错。

解决步骤 #

1. 强制Spark使用本地文件系统 #

在创建SparkSession时，通过配置将默认文件系统切换为本地：

from pyspark.sql import SparkSession

appName = "你的应用名称"
spark = SparkSession.builder \
    .master("local[*]") \
    .appName(appName) \
    .config("spark.hadoop.fs.defaultFS", "file:///") \
    .getOrCreate()

2. 正确设置检查点路径 #

切换到本地文件系统后，直接使用Windows原生路径格式即可：

# 两种写法都有效
spark.sparkContext.setCheckpointDir("C:/tmp")
# 或者用file协议格式
# spark.sparkContext.setCheckpointDir("file:///C:/tmp")

3. 设置spark.sql.streaming.forceDeleteTempCheckpointLocation #

有三种方式可以开启这个参数：

• 代码内配置：在创建SparkSession时添加配置项：

  spark = SparkSession.builder \
      .master("local[*]") \
      .appName(appName) \
      .config("spark.hadoop.fs.defaultFS", "file:///") \
      .config("spark.sql.streaming.forceDeleteTempCheckpointLocation", "true") \
      .getOrCreate()
  

• 修改Spark配置文件：在Spark安装目录的conf/spark-defaults.conf中添加一行：

  spark.sql.streaming.forceDeleteTempCheckpointLocation true
  

• 命令行启动时指定：运行PySpark时通过参数传递：

  pyspark --conf spark.sql.streaming.forceDeleteTempCheckpointLocation=true
  

关键解释 #

为什么HDFS URL里会出现C:/？因为你使用的是带Hadoop的Spark版本，默认文件系统是HDFS。当你传入Windows本地路径时，Spark会直接把这个路径拼接到HDFS的默认地址（hdfs://localhost:9000）后面，形成非法的HDFS路径。切换默认文件系统为本地后，Spark会正确解析Windows的盘符路径，不再走HDFS规则。

内容的提问来源于stack exchange，提问作者Joseph Hwang