Spark实战：从Pandas到分布式大数据分析的完整Demo与避坑指南-代码聚汇网

Spark实战：从Pandas到分布式大数据分析的完整Demo与避坑指南

小雨果1号·2026-09-04·阅读 22 GEO检测（免费）

Apache SparkPySparkPandas

|难度：普通|阅读约 51 分钟

玩数据的人应该都有过这样的经历：想搜一个实际能跑通的 Spark 例子，结果首页一半是“Gemini 永久会员”“某某地区不可用”之类的标题党，点进去全是引流话术；另一半是官网文档，看完还是不知道第一步怎么敲。我最近正好在整理一套给团队内部用的 Spark 数据处理与分析示例，标题也带着 Gemini 和 Python，但核心其实是一个特别朴素的问题：当你手头的数据从“几百万行 Pandas 还能忍”变成“一天几个 G 的日志、几千个文件”时，怎么用 Apache Spark 把活干完、干稳、还能让业务同学看得懂结果。这篇文章我就把那个 demo 完整拆开，从环境搭建、代码逻辑到性能和坑，按我实际折腾的顺序写下来，希望帮你少走几段弯路。

先交代一下背景和适合谁看：我对 Spark 的了解起点不算高，之前主要写 Python + Pandas + SQL，真正在本地把 Spark 跑起来、再迁移到集群上，前后花了两周。这篇文章适合两类人：一是数据分析师或后端开发，想用 Spark 处理比单机内存大的数据，但不知道怎么优雅入门；二是已经能跑通官方 word count，但遇到日志分析、用户行为统计、多表 Join 这类“真实业务问题”就发怵的同学。我会用一个可复现的模拟电商日志 demo，把 Spark 的 DataFrame、Spark SQL、调试和性能调优串起来，最后还附了我踩过的几个典型坑和排查思路。

1. 先把“分布式”这件事用大白话讲透

1.1 单机 Python 处理大数据的极限到底在哪

很多人第一次被 Spark 吸引，是因为 Pandas 跑大 CSV 时内存爆了。我见过不少同学直接 pd.read_csv('all_logs.csv')，然后看着内存一点点变红，最后进程被杀掉。Pandas 处理数据时有一个核心前提：数据必须全部加载进内存，而且中间过程的临时对象还会成倍占用空间。比如一列字符串在 Pandas 里默认就是 Python str 对象，一个 10 字符的字符串可能占 60 到 80 字节，远比你想的大。数据量一旦到 10 G 以上，单机 16 G 或 32 G 内存基本就“无解”了。

但这里有个容易被误解的点：Spark “能处理大数据”不是因为它有魔法，而是因为它把数据切碎后分发到多台机器的内存和磁盘上并行处理。一台机器的瓶颈变成 N 台机器分担，内存不够就落盘。它的设计哲学是“分布式计算框架”，不是“单机加速版 Pandas”。所以正确理解 Spark，先要忘掉“我在跑一个大 DataFrame”这个思维，改成“我在声明一堆对分布式数据集的操作”。

1.2 Driver、Executor、Shuffle 在真实任务中分别扮演什么角色

用一个生活类比：你要统计一个城市所有书店的销量。单机版 Pandas 相当于你一个人把所有书店的账本搬进家里，慢慢翻。Spark 的做法则是请一群店员（Executor）去各自的片区（数据分区）分别统计，你是店主（Driver）只负责派活和收结果。

Driver：跑你写的主程序，负责解析逻辑、生成执行计划、调度任务。Driver 挂了，整个任务就挂了。
Executor：真正干活的进程。每个 Executor 上有多个 slot（可以理解为线程），执行 Driver 分下来的 task。
RDD / DataFrame：只是“数据的抽象描述”，代表一个分布式的数据集合。它被切成若干个 partition 分散在各 Executor 上。
Shuffle：这是 Spark 里最昂贵、也最容易出现 OOM 的操作。比如按用户 ID 做 groupBy，相同用户的数据必须从不同分区聚到同一个 Executor 上，跨节点搬运数据的过程就叫 Shuffle。

你不需要一开始就记住所有名词，但必须要有一个感知：写 Spark 代码时，凡是要把数据“重新洗牌”的操作（groupBy、join、distinct、orderBy），耗时和资源消耗都会上一个量级。后面性能调优那节还会详细说。

1.3 核心认知：懒加载（Lazy Evaluation）和血缘关系

我第一次跑 Spark 时犯过一个新手错误：写一行 df = spark.read.csv(...) 然后 print(df)，发现什么都没输出，一度以为读取失败了。其实 Spark 是懒加载的，read.csv 只是定义了数据源和 schema，并不会立即读文件；只有遇到 count()、show()、write 这类“行动操作”时，前面的转换逻辑才会真正执行。

这个设计的好处是，Spark 可以把一连串转换操作构建成一个有向无环图（DAG），等到真正要出结果时一起优化执行。比如你先后做了多个筛选、列裁剪、聚合，Spark 可能把没用的列一开始就不读。理解懒加载后，你就明白为什么 Spark 程序里常看到“先构建 Transformations，最后才 Action”的风格。也是这套血缘机制，让 Spark 在某个节点任务失败后，可以只重算失败的分区，而不是全盘重跑。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 本地搭建 Spark 环境前，先解决这些版本细节

2.1 Java 版本与 Spark 版本的兼容矩阵

很多人跑不起来 Spark，第一坑就是 Java 版本。Spark 本身用 Scala/Java 实现，所以本地必须装 JVM。不同 Spark 版本对 Java 的兼容范围不同，我用的组合是 Spark 3.5.x + Java 8/11/17 都可以，但 3.5 开始官方对 Java 17 的支持也更完整；而 Spark 3.2 之前如果配 Java 17 会直接报 “UnsupportedClassVersionError” 之类的问题。

如果你不确定装哪个，我的建议是：装 Spark 3.5.1 或 3.5.x 最新小版本 + Java 8（企业里最稳）或 Java 11（个人机器没问题）。先跑通 demo 比盲目追新重要。检查 Java 环境用：

bash复制java -version

如果返回的是 Java 8，那建议直接选 Spark 3.5 以下对应版本，或者升级 JDK 到 11/17。为了少出错，我把常用组合整理成了表：

Spark 版本	推荐 Java 版本	可选 Python 版本	备注
3.0.x	8/11	3.6-3.9	较老，不建议新项目
3.3.x	8/11	3.7-3.10	兼容性好
3.5.x	8/11/17	3.8-3.11	目前最省心的选择
4.0 预览版	17/21	3.9+	尝鲜可以，生产慎用

2.2 下载 Spark、配置环境变量，以及 Windows/Mac 的差异

我是在 macOS 上先跑通的，后来帮同事在 Windows 上排障时发现，环境变量配不好是最常见的问题。下载时去官网选 “Pre-built for Apache Hadoop 3.3 and later” 这种包，本地没有 Hadoop 集群也能直接跑 local 模式，因为这个包内置了 Hadoop 客户端库。

macOS/Linux 用户在 .zshrc 或 .bashrc 里加：

bash复制export SPARK_HOME="$HOME/opt/spark-3.5.1-bin-hadoop3"
export PATH="$SPARK_HOME/bin:$PATH"
export PYSPARK_PYTHON=python3
export PYSPARK_DRIVER_PYTHON=python3

Windows 用户除了加 SPARK_HOME 和 PATH，还要注意：Spark 3.x 在 Windows 下跑 local 模式经常会让你提供 winutils.exe，因为 Hadoop 原生库找不到。一个简单处理是下载对应 Hadoop 版本的 winutils 放到某个目录，然后设置：

bash复制set HADOOP_HOME=D:\hadoop
set PATH=%HADOOP_HOME%\bin;%PATH%

不设置的话，常见错误是 Failed to locate the winutils binary in the Hadoop binary directory。不过它有时只是警告，不影响 local 模式任务；但如果你后面要读写本地文件系统做 checkpoint，可能就会报错。我的建议是顺手配好，省得排查时疑神疑鬼。

2.3 pyspark 安装与 VSCode/Jupyter 下的正确打开方式

环境变量配好后，还要装 Python 侧的库：

bash复制pip install pyspark

这里有一个容易混淆的点：pip install pyspark 会连 Spark 的 JVM 二进制一起装，所以即使你不单独下载 Spark tar 包，也能跑 local 模式。但如果你要运行 spark-submit 提交脚本，还是建议按 2.2 的方式下载一套 Spark 放到 SPARK_HOME。

在 VSCode 或 Jupyter 里跑 demo 时，我通常用下面这段代码作为入口：

python复制from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .appName("LocalSparkDemo") \
    .master("local[*]") \
    .config("spark.sql.shuffle.partitions", "4") \
    .getOrCreate()

.master("local[*]") 表示用本机所有 CPU 核心跑；spark.sql.shuffle.partitions 我先设成 4，只是为了本地小数据别动不动产生 200 个任务分片。后面我还会专门聊这个参数对性能的影响。

注意：如果你用的是 Jupyter，并且想在多个 cell 里共享同一个 SparkSession，尽量只创建一次。重复执行 getOrCreate() 本身不会报错（同名 SparkSession 会复用），但如果反复 stop() 再创建，容易出现日志刷屏、任务线程残留等小毛病。

3. 一个马上能跑通的数据分析 Demo：模拟电商行为日志

3.1 造数据：用 Python 生成一份“像样”的用户访问日志

纯讲 API 太干了，最好有个真实手感的数据集。我写了一个简单的模拟数据生成脚本，生成 20 万条用户访问日志。思路是：随机生成用户 ID、访问时间、页面 ID、页面类型、停留时长、是否登录、设备类型等字段。这种“行为日志”结构和很多公司埋点日志相似，能覆盖分组、Top N、去重、时间窗口等常用分析操作。

python复制import random
import datetime
import csv

random.seed(42)

pages = [
    ("home", "首页"),
    ("search", "搜索页"),
    ("detail", "商品详情页"),
    ("cart", "购物车页"),
    ("checkout", "结算页"),
    ("order_success", "下单成功页"),
]
devices = ["pc", "mobile", "app", "wechat"]

start_time = datetime.datetime(2024, 12, 1, 0, 0, 0)
end_time = datetime.datetime(2024, 12, 7, 0, 0, 0)

def random_time():
    delta = end_time - start_time
    random_seconds = random.randint(0, int(delta.total_seconds()))
    return start_time + datetime.timedelta(seconds=random_seconds)

with open("click_logs.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["user_id", "event_time", "page_type", "page_id", "device", "is_login", "duration_sec"])

    for i in range(200000):
        user_id = f"u{random.randint(1, 30000)}"
        event_time = random_time().strftime("%Y-%m-%d %H:%M:%S")
        page_type, page_name = random.choice(pages)
        page_id = f"{page_type}_{random.randint(1, 500)}"
        device = random.choice(devices)
        is_login = 1 if random.random() > 0.3 else 0
        duration_sec = random.randint(3, 3600) if is_login else random.randint(1, 120)
        writer.writerow([user_id, event_time, page_type, page_id, device, is_login, duration_sec])

这个 CSV 大概十几 MB，对 Spark 来说是小菜，但对演示足够。20 万条量级用 Pandas 也能跑，但我们要的是把思路跑通，再把数据量换成 2 亿条也成立。

3.2 读取数据并做“数据体检”：总量、缺失值和记录格式

Spark 读取 CSV 时最怕 schema 推断错。比如 user_id 是 u123 这种字符串，duration_sec 如果是整数，Spark 一般能推对；但如果你先手动指定 schema，后面能省很多格式转换的麻烦。这里我直接让 Spark 推断，并打印出类型和统计信息：

python复制df = spark.read.option("header", True) \
    .option("inferSchema", True) \
    .csv("click_logs.csv")

df.printSchema()

# 总记录数
total_cnt = df.count()
print(f"总记录数: {total_cnt}")

# 缺失值概况：主要看 user_id / event_time / page_type
from pyspark.sql.functions import col, isnan, isnull, sum as _sum

df.select(
    _sum(col("user_id").isNull().cast("int")).alias("user_id_null"),
    _sum(col("event_time").isNull().cast("int")).alias("event_time_null"),
    _sum(col("page_type").isNull().cast("int")).alias("page_type_null"),
    _sum(col("device").isNull().cast("int")).alias("device_null"),
).show()

df.printSchema() 输出长这样：

text复制root
 |-- user_id: string (nullable = true)
 |-- event_time: string (nullable = true)
 |-- page_type: string (nullable = true)
 |-- page_id: string (nullable = true)
 |-- device: string (nullable = true)
 |-- is_login: integer (nullable = true)
 |-- duration_sec: integer (nullable = true)

注意 event_time 被推断成 string，因为 CSV 本身没有时间类型。后续做时间窗口统计时，需要先转成 Timestamp 类型。

3.3 核心分析一:哪些页面访问量最高

第一个业务问题是最简单的：给业务同学看 Top 10 热门页面。这里会用到 groupBy 和 orderBy，是 Spark 最基础也最高频的操作。

python复制from pyspark.sql.functions import count, sum, avg, countDistinct

top_pages = df.groupBy("page_type") \
    .agg(
        count("*").alias("pv"),
        countDistinct("user_id").alias("uv")
    ) \
    .orderBy(col("pv").desc())

top_pages.show(10)

结果里能看到首页访问量肯定最高，但更有意思的是“搜索页”和“商品详情页”的 UV 对比。如果访客集中在详情页却很少去搜索页，也许是推荐位做得比搜索更好；如果搜索页 PV 高但 UV 不高，可能是部分用户在反复搜索。这种粒度在 Pandas 里就是几行代码，在 Spark 里也就多了一个 SparkSession 的壳，完全没有想象中复杂。

3.4 核心分析二:按天统计活跃用户数和人均浏览量

接下来是更偏“数据运营日报”的需求：统计 7 天内每天的独立访客数（UV）、总访问量（PV）、人均浏览页数。这里需要把字符串时间转成日期，再按天聚合：

python复制from pyspark.sql.functions import to_date, date_format

df_with_day = df.withColumn("day", to_date(col("event_time"), "yyyy-MM-dd HH:mm:ss"))

daily_stats = df_with_day.groupBy("day").agg(
    count("*").alias("pv"),
    countDistinct("user_id").alias("uv"),
    (count("*") / countDistinct(col("user_id"))).alias("pv_per_uv")
).orderBy("day")

daily_stats.show(7)

注意我在 groupBy("day") 之后直接用了两个聚合函数 count 和 countDistinct，Spark 支持在一个 agg 里写多个聚合，不需要先算 PV 再去算 UV。这里有个小技巧：人均浏览量最好用 count(*) / countDistinct(user_id)，不要先取出明细再在 Python 侧算，因为分布式环境下把明细 collect 到 Driver 端是大忌。

3.5 核心分析三：把“停留时长”跑成一个留存/活跃的简单信号

最后加一个稍微进阶的指标：统计“登录用户”和“未登录用户”的平均停留时长，再按设备类型拆分。这个分析能反映不同设备上用户的质量，对判断刷量流量也有帮助（异常流量往往是未登录、高 PV、极短停留）。

python复制device_stats = df.groupBy("device", "is_login").agg(
    count("*").alias("pv"),
    avg("duration_sec").alias("avg_duration")
).orderBy("device", col("pv").desc())

device_stats.show(100)

把 is_login 从 0/1 映射成可读文案时，也可以用 when 函数：

python复制from pyspark.sql.functions import when

df_labeled = df.withColumn(
    "login_status",
    when(col("is_login") == 1, "已登录").otherwise("未登录")
)

把这些结果拼接起来，一个“用 Spark 做数据分析”的小 demo 就算跑通了。demo 本身不复杂，但它已经覆盖了 read/groupBy/agg/join/withColumn 这些核心 API，后面的进阶内容都是在这个骨架上的扩展。

4. 从 Demo 走向工程化：SQL、UDF 和外部存储

4.1 DataFrame API 和 Spark SQL，怎么选

如果团队里的数据分析师更熟 SQL，那直接把 DataFrame 注册成临时视图，用 spark.sql() 跑 SQL 会更顺。比如把上一个统计翻译成 SQL：

python复制df_with_day.createOrReplaceTempView("click_logs")

daily_stats_sql = spark.sql("""
    SELECT day,
           COUNT(*) AS pv,
           COUNT(DISTINCT user_id) AS uv
    FROM click_logs
    GROUP BY day
    ORDER BY day
""")

我个人建议是：复杂到三张表以上的 Join，用 SQL 写更直观；需要灵活控制、反复复用的逻辑，用 DataFrame API 更合适。实际上两者底层会生成同样的执行计划，性能差异不大，选哪种取决于后续维护者是谁。给业务同学做交付时，我常常先用 SQL 写出口径版本，再翻译成 PySpark API 放进自动化脚本，两边能互相对照避免口径不一致。

4.2 自定义函数 UDF：能不用就不用，要用得克制

Spark 里可以用 Pandas UDF（矢量化）来定义自定义函数，比如把页面 ID 拆出页面类型。但要记住：普通 Python UDF 会把每一行数据从 JVM 传到 Python 进程再传回来，序列化开销很大，处理 1 亿行时几千倍性能差距都有。

在我那个 demo 里，要解析 page_id 里的“detail_123”这种东西，本来可以用 split 函数：

python复制from pyspark.sql.functions import split

df = df.withColumn("page_id_part", split(col("page_id"), "_")[0])

这属于内置 SQL 函数，完全不会走 Python UDF 的开销。只有内置函数实在做不到的业务逻辑，才考虑写 UDF，而且最好用 pandas_udf 而不是普通 udf：

python复制from pyspark.sql.functions import pandas_udf
import pandas as pd

@pandas_udf("string")
def device_group(device_series: pd.Series) -> pd.Series:
    return device_series.map(lambda x: "移动端" if x in ("app", "wechat") else "PC端")

4.3 结果写回 MySQL / 达梦 / 数仓的通用姿势

日常分析中，结果最好写到业务同学能直接查询的地方。Spark 提供了统一的 JDBC 写入方式。我实际试过把结果写回 MySQL 和达梦数据库(KBMS)，思路一致：只要有对应的 JDBC 驱动 jar，就能通过 format("jdbc") 写入。

以 MySQL 为例：

python复制daily_stats.write \
    .mode("overwrite") \
    .format("jdbc") \
    .option("url", "jdbc:mysql://localhost:3306/analytics") \
    .option("dbtable", "daily_page_stats") \
    .option("user", "root") \
    .option("password", "your_password") \
    .option("driver", "com.mysql.cj.jdbc.Driver") \
    .save()

跑之前需要把 mysql-connector-java 的 jar 放到 Spark 的 jars 目录，或者通过 spark.jars 配置传入：

python复制spark = SparkSession.builder \
    .config("spark.jars", "/path/to/mysql-connector-java.jar") \
    .getOrCreate()

达梦数据库的适配思路也类似。达梦提供的 JDBC 驱动通常是 DmJdbcDriver18.jar，连接 URL 带上 dm:// 前缀，它兼容大部分 JDBC 标准 SQL 语法。比如：

python复制spark.read \
    .format("jdbc") \
    .option("url", "jdbc:dm://192.168.1.100:5236") \
    .option("dbtable", "some_table") \
    .option("user", "SYSDBA") \
    .option("password", "your_password") \
    .option("driver", "dm.jdbc.driver.DmDriver") \
    .load()

不过需要提醒一下国产数据库和 Spark 集成时的几个兼容点：一是 schema 大小写，有时候表名/列名默认是大写，Spark 这边要加 quoteIdentifiers 或注意列名匹配；二是达梦对标准 JDBC 的 upsert 语法不完全兼容，所以 mode("overwrite") 时尽量先删表或创建临时表再做 merge，别依赖 Spark 自动生成的所有方言。因为我手上也正好有团队在捣鼓“达梦数据库与 Spark 适配”，这类问题确实存在，但多数都能用“先读后写、SQL 显示指定 schema”的方式绕开。

4.4 用分区写出的方式避免小文件爆炸

如果结果要落盘到 HDFS 或本地目录，而不是直接写数据库，用 partitionBy 按统计日期分区是常见优化手段。例如：

python复制daily_stats.write \
    .mode("overwrite") \
    .partitionBy("day") \
    .parquet("output/daily_stats.parquet")

但如果你直接用默认设置写，很容易写出一堆小文件。一次 Overwrite 产生的文件数基本等于最后 RDD 的分区数，如果不调整，即使数据量很小也可能生成几十个碎片文件。后面查询时每扫一个小文件都有额外开销，得不偿失。比较稳妥的做法是，在写入前用 coalesce(n) 控制分区数，或在 Spark 3.2+ 用 repartition 按分区键控制文件粒度：

python复制daily_stats.coalesce(1).write \
    .mode("overwrite") \
    .partitionBy("day") \
    .parquet("output/daily_stats.parquet")

.coalesce(1) 适合最后结果小、想直接看单文件的情况；如果结果很大，别用 coalesce(1)，而是根据目标大小估算分区数，并且尽量让分区键和后续查询过滤条件一致。

5. 本地跑 Spark 时我踩过的坑，以及完整排查链路

5.1 Shuffle 阶段 OOM，原来是 `spark.sql.shuffle.partitions` 惹的祸

我在本地第一次跑比较复杂的 groupBy 时，任务在其中某个 stage 报了 java.lang.OutOfMemoryError。第一反应是调大 Executor 内存，但调大后仍然会出现。后来看了 Stage 页面，才发现问题在于默认的 Shuffle 分区数是 200，而我的本地机器只有 8 核，20 万条数据却被打散到 200 个分区，每个分区又要开 task 处理，整机线程切换和内存开销巨大。虽然数据不大，但每个 task 都有固定调度成本，反而把资源吃满了。

解决方案很简单，在创建 SparkSession 时就设置：

python复制.config("spark.sql.shuffle.partitions", "8")

这个数字通常建议设置为可用 CPU 核数的 2 到 4 倍。本地小数据跑测试时，我一般直接设成和核数相同；集群上跑大任务时再梯度调参。

排查链路给大家参考：先看 Application UI 的 Stage 列表，是哪个 stage 失败；再看失败 task 是发生在 read 还是 shuffle。如果发生在 shuffle read，大概率是分区数过多或 Executor 内存不足。如果是数据倾斜，还要看某个 task 的 input size 是否远高于中位数。不要一上来就无脑加内存，加内存只是延缓问题，不解决倾斜和分区不合理。

5.2 Python 解释器版本不匹配导致 pyspark 无法启动

有一个非常隐蔽的坑：如果一个环境里用 conda 装了 Python 3.11，系统全局 Python 还是 3.9，并且你在 bash 里配了 PYSPARK_PYTHON=python3，那 python3 到底指向哪个，直接决定了 pyspark 能不能启动。

我遇到过启动后马上打印一串 Python in worker has different version 3.9 than that in driver 3.11 然后失败的。解决方法是用绝对路径指定解释器：

bash复制export PYSPARK_PYTHON=/opt/miniconda3/envs/pyspark_env/bin/python
export PYSPARK_DRIVER_PYTHON=/opt/miniconda3/envs/pyspark_env/bin/python

这件事的教训是：不要把 python3 这种东西放进依赖路径。因为 PySpark worker 进程是通过 subprocess 启动 Python 的，它读取的是 PYSPARK_PYTHON 环境变量里的解释器。一旦 driver 和 worker 解释器版本不一致，序列化协议就可能对不上。

5.3 和 Pandas 互转时出现的 Py4J 类型问题

很多从 Pandas 转过来的同学喜欢中间把 Spark DataFrame 转成 Pandas 再处理：

python复制df_pd = df.toPandas()

小数据没问题，但要知道 toPandas() 会把所有数据 collect 到 Driver 端内存，大数据一次就撑爆了。另一个坑是，如果你在 Spark DataFrame 里有 map 类型或嵌套结构，转 Pandas 后列类型可能变成 Python list/dict，处理完再转回 Spark 时可能出现 schema 推断错误。

我的建议是：能用 Spark 内置函数完成的，绝对不要 toPandas()；只有要交给人看、或需要配合 matplotlib 画小图时，才 collect 结果集且保证结果集够小。

5.4 任务显示成功但目标路径没有输出文件

有段时间我在跑完写 parquet 后，发现目录是空的，日志里也没报错。排查后发现是写入模式和数据源读入路径的问题。原来我用 spark.read.csv("data/logs/") 读目录时，同一个输出目录也被包含在输入源里。Spark 在任务开始时读了一次，写入时把结果写到同目录下，导致本地文件系统出现一种“读到一半、写了一半”的诡异状态。虽然最后 job 成功，但文件被后续任务覆盖或移动后目录为空。

解决办法是：输入路径和输出路径严格分开，写完后用原子方式做目录切换。另外一个常见情况是任务跑在了带有 checkpoint 的目录，而 checkpoint 和输出目录在同一份表路径下，也会导致类似问题。这属于数据工程里很经典的“读写同一路径”问题，务必在设计目录结构时就避免。

5.5 空结果不等于没跑，先检查过滤条件格式

还有一次我写时间过滤条件，WHERE event_time >= '2024-12-01'，结果一条记录都没返回。后来发现 CSV 里的 event_time 是 2024-12-01 10:30:00 这种字符串，而字符串比较是按字典序，2024-12-01 10:30:00 确实小于 2024-12-01，所以全部被过滤掉了。改成先 to_date 再过滤就正常了。这也是新手最容易忽略的点：字符串时间比较和真正的时间语义不是一回事。

排查顺序也更清晰：

先看是否符合预期的 schema（printSchema）
做一次不带过滤的 count()，确认源数据能读
再加过滤条件，逐步缩小范围
如果过滤字段是时间，优先转成 TimestampType

6. 几件真正提升效率的事：配置、监控和写作习惯

6.1 让 SparkSession 默认参数更适合本地开发

我本地开发有一套顺手的基础配置，可以先存成一个工具模块。每次新建项目复制这个工具就能快速开始：

python复制def create_local_spark(app_name="demo"):
    return SparkSession.builder \
        .appName(app_name) \
        .master("local[*]") \
        .config("spark.sql.shuffle.partitions", "8") \
        .config("spark.sql.adaptive.enabled", "true") \
        .config("spark.sql.adaptive.coalescePartitions.enabled", "true") \
        .config("spark.driver.memory", "4g") \
        .getOrCreate()

spark.sql.adaptive.enabled 是 Spark 3.0 以后的 AQE（自适应查询执行）功能，它会根据实际运行数据量自动调整分区和 Join 策略，对易用性提升很大。如果你的版本是 3.2+，我强烈建议默认开启。

6.2 UI 页面才是排查问题的第一现场

很多人跑 Spark 报错只会看终端红字，其实本地模式启动后访问 http://localhost:4040 能看到每个 Stage 的详情，包括每个 task 的输入数据量、Shuffle 读写量、失败重试次数。遇到性能问题，不要猜，先看 UI 上的这些指标。例如某个 stage 里有几个 task 的 Shuffle Read 数据量是其他 task 的 10 倍以上，就说明发生了数据倾斜。

我常做的优化是把热点 key 加上盐值（salting）再聚合，但这种优化往往是在 UI 确认倾斜后才值得做。没确认倾斜前就写复杂策略，属于过早优化，反而增加维护成本。

6.3 用 AI 辅助写 PySpark 是一个真香但需要小心的事

最近大家讨论 Gemini、Copilot 这类工具比较多，我也经常让 AI 帮忙生成 PySpark 代码。我的实际体感是：标准分析场景，比如 groupBy 聚合、窗口函数、时间处理，AI 生成的代码相当能打；但一旦涉及特定版本 API、JDBC 驱动、数据源方言，它经常会一本正经地给一个错误参数名或过时接口。所以我的建议是：不要直接复制粘贴生产代码，而是把 AI 生成的“思路”拿到 Spark UI 和小数据集上先验证。

另外，因为我是拿着“Gemini 永久会员”这个标题点进来的，这里也多说一句：我其实不建议去买那种“永久会员”共享号、代充号，这类关键词下大概率是营销号或账号贩子，风险很高。真要体验大模型辅助编程，走正规渠道订阅或先用免费额度就够学习用了。网上所谓“永久会员”不是长期可靠的东西，远不如自己把 Spark 调通带来的能力增长实在。

6.4 一份可参考的 PySpark 项目目录结构

最后给一个工程化的目录结构建议。本地 demo 可以随意写单文件，但真正要长期跑的脚本，最好用 package 管理起来，避免“文件名带 v2_final”这种灾难：

text复制spark_demo/
├── config.py              # SparkSession 配置，统一入口
├── etl.py                 # 读数据、清洗、加工
├── analysis.py            # 统计指标计算
├── writer.py              # 写库/写文件
├── jobs/
│   ├── daily_report.py    # 每天调度入口
│   └── ad_hoc_query.py    # 临时查询
├── tests/
│   ├── test_etl.py
│   └── test_analysis.py
└── requirements.txt

整套代码最好支持“命令行传参指定日期/环境”的输入方式，而不是把日期硬编码在代码里。这样后续接调度系统（Airflow/DolphinScheduler）时能最小化改造。我自己的经验是，Spark 任务搞得越像标准 Python 工程，越容易维护。别因为它是“大数据框架”就忘了软件工程的基本原则。

7. 一些个人体会

从“Pandas 爆内存”到可以安心用 Spark 跑几亿行数据，中间的门槛没有想象中高。最痛苦的反而不是 API 学不会，而是思维转换:面对一堆数据时，得先想清楚哪些操作是分布式的、哪些操作天然会触发 Shuffle、哪里需要调整分区。这个 demo 里的所有逻辑换到集群上，基本不需要改动太多；真正要改的是资源参数和分区策略。

我不太建议一上来就啃《Spark 权威指南》或者纠结 RDD 的底层实现。先把本地环境跑通，用一份自己熟悉的业务数据，把 groupBy / join / window / write 四个最常用的场景各写一遍，很多概念会瞬间串起来。等你真正遇到集群性能问题，再回头翻书，效率会高得多。希望这份记录能帮你把第一脚踢开。