## 1. 本地 PySpark 实验的四大基石环节 我在实验室带学生做大数据实践时，最常听到的一句话是：“为什么我 pip install pyspark 后 run 就报错？”——八成卡在环境链上。PySpark 不是普通 Python 库，它背后拖着一个 Java 运行时、一个 Spark 引擎、一套路径联动机制。少一环，整个链条就断。这四大环节不是线性步骤，而是相互咬合的齿轮：JDK 没配对，Spark 启动不了；SPARK_HOME 指错了，pyspark 会悄悄降级到内嵌 mini 模式（连日志都懒得打）；Python 版本越界，连 import 都失败。我试过在 macOS M1 上用 Python 3.12 装 pyspark 3.4，结果 driver 直接 core dump——官方支持清单里明写着 Python ≤3.11。所以别急着写代码，先让环境“呼吸顺畅”。你不需要下载源码编译，也不需要部署 ZooKeeper，只要把 JDK、Python、Spark 二进制包、pyspark 四者版本对齐、路径打通、权限理清，本地实验就能稳稳跑起来。实测下来，从零开始搭通整套环境，熟练者 15 分钟，新手预留 40 分钟更稳妥——多花的时间，基本都耗在反复检查 JAVA_HOME 是否漏了 bin、SPARK_HOME 是否多了一层 spark-3.4.2-bin-hadoop3 目录、以及 pip 安装时是否误用了 --user 导致全局找不到模块。 ## 2. JDK 配置与 Java 运行时校验 Spark 是用 Scala 写的，而 Scala 运行在 JVM 上，所以 PySpark 的 driver 和 executor 最终都要靠 Java 字节码撑腰。很多人以为装个 JRE 就够，其实不行——Spark 编译和运行阶段都需要 javac、jps、jstat 这些开发工具，必须装完整 JDK。我踩过最深的坑是在 Ubuntu 22.04 上默认装了 openjdk-11-jre，结果 spark-submit 报错 “NoClassDefFoundError: javax/tools/JavaCompiler”，折腾半小时才发现缺的是 jdk，不是 jre。现在推荐直接用 OpenJDK 17（LTS 版本），它被 Spark 3.3+ 全面认证，兼容性比 JDK 8 更稳，且避免了旧版中常见的 GC 参数冲突。安装后别急着 export，先验证：打开终端敲 `java -version` 和 `javac -version`，两个输出的版本号必须完全一致，且主版本号是 17。接着配置 JAVA_HOME，关键点在于路径必须精确到 JDK 根目录，不能带 /bin。比如你解压的是 `jdk-17.0.2`，那么 `export JAVA_HOME=/opt/java/jdk-17.0.2` 才对；如果写成 `/opt/java/jdk-17.0.2/bin`，后续 Spark 启动时会找不到 `$JAVA_HOME/jre/lib/ext` 下的核心 jar。配置完别忘了把 `$JAVA_HOME/bin` 加进 PATH，否则 `spark-shell` 会提示 “command not found”。最后一步校验：运行 `echo $JAVA_HOME` 看输出是否干净无空格，再执行 `$JAVA_HOME/bin/java -XshowSettings:properties -version 2>&1 | grep java.home`，确认输出路径和你设置的完全一致。这三步做完，Java 这块才算真正落定。 ## 3. Spark 二进制包选取与环境变量落地 Spark 官网提供多种预编译包，别直接点 “Download Spark” 拿最新版。你需要看清楚后缀：`spark-3.4.2-bin-hadoop3.tgz` 表示它内置了 Hadoop 3.x 的 client 库，能直接读写 HDFS、S3、OSS；而 `spark-3.4.2-bin-without-hadoop.tgz` 是纯 Spark 引擎，读本地文件没问题，但一旦碰 `spark.read.parquet("hdfs://...")` 就抛 NoClassDefFound。我们做本地实验，选 `hadoop3` 版本最省心。下载后解压，注意解压命令别用 `tar -xvf`（可能保留原权限导致执行失败），推荐 `tar -zxvf spark-3.4.2-bin-hadoop3.tgz --no-same-owner`。解压完得到一个 `spark-3.4.2-bin-hadoop3` 目录，这就是你的 SPARK_HOME。把它软链接到固定路径最稳妥，比如 `ln -s ~/Downloads/spark-3.4.2-bin-hadoop3 ~/spark`，然后 `export SPARK_HOME=$HOME/spark`。PATH 要加两处：`$SPARK_HOME/bin`（让 spark-submit、pyspark 命令可用）和 `$SPARK_HOME/sbin`（集群模式启动脚本）。别漏掉 `$SPARK_HOME/jars`——虽然 pyspark pip 包自带核心 jar，但某些 connector（如 delta-io）仍需手动丢进这里。配置生效后，运行 `pyspark --version`，应该立刻打印出 Spark 3.4.2 和 Python 版本；如果卡住或报 “Failed to find Spark jars directory”，说明 SPARK_HOME 路径有误或权限不足（macOS 上常见，需 `chmod -R 755 $SPARK_HOME`）。我还习惯加一行 `export PYSPARK_PYTHON=python3`，避免系统里多个 Python 版本时 pyspark 自作主张调用 python2.7。 ## 4. PySpark 库安装与本地模式运行机制 `pip install pyspark` 这条命令看似简单，背后逻辑很实在：它不只装 Python 接口，还会自动下载并解压一个轻量级 Spark 二进制副本到 `site-packages/pyspark/jars/` 下，并设置好内部 classpath。这意味着，即使你没配 SPARK_HOME，`pyspark` 命令也能跑起来——但它走的是“内嵌模式”，所有计算都在单个 JVM 进程里完成，无法体现分布式特性。所以我的建议是：**始终优先使用外部 Spark 二进制包 + pip install pyspark 的组合**。这样既能复用你精心配置的 JDK 和 Spark 参数，又能让 Python 代码直连真实 Spark 引擎。安装时务必指定版本，比如 `pip install pyspark==3.4.2`，和你的 Spark 二进制包严格对齐。验证安装是否成功，别只看 import 能否通过，要跑一段真逻辑：新建 test_pyspark.py，写三行： ```python from pyspark.sql import SparkSession spark = SparkSession.builder.master("local[*]").appName("test").getOrCreate() print(spark.sparkContext.version) ``` 运行 `python test_pyspark.py`，如果输出 `3.4.2`，说明连接成功；如果报 `Py4JJavaError` 或卡在 “Starting Spark application…”，大概率是 JAVA_HOME 或 SPARK_HOME 没生效，或者端口被占用（Spark 默认用 4040，可加 `.config("spark.ui.port", "4041")` 换端口）。本地模式下，“local[*]” 中的 * 表示用满所有 CPU 核心，但内存默认只有 1G——小数据集够用，一旦处理百万行 CSV，你会看到频繁 GC 和 OOM。这时得主动调大：`.config("spark.driver.memory", "4g")`。记住，`spark.stop()` 不是可选项，是必选项。我见过太多人忽略它，导致 driver 进程常驻内存，下次运行时端口冲突，debug 半天才发现是上次没关干净。 ## 5. SparkSession 创建与 DataFrame 实验全流程 创建 SparkSession 是 PySpark 的入口，但它的 builder 链式调用里藏着很多实用细节。`.master("local[2]")` 表示开 2 个线程模拟 worker，比 `local[*]` 更可控，适合调试；`.appName("ETL-Job-2024")` 的名字会显示在 Spark UI 的 Application Name 列，方便你一眼区分不同任务。配置项别堆在 builder 里，建议抽成字典统一管理： ```python conf_dict = { "spark.sql.adaptive.enabled": "true", "spark.sql.adaptive.coalescePartitions.enabled": "true", "spark.driver.memory": "3g", "spark.sql.adaptive.localShuffleReader.enabled": "true" } spark = SparkSession.builder \ .master("local[2]") \ .appName("DataAnalysis") \ .config(conf=conf_dict) \ .getOrCreate() ``` 构建 DataFrame 时，别只用 `createDataFrame([(…), (…)], ["col1", "col2"])` 这种玩具方式。实操中，你一定会读 CSV、JSON、Parquet。比如读本地 CSV：`df = spark.read.option("header", "true").csv("/tmp/data.csv")`，这里 `option("header", "true")` 必须显式声明，否则第一行会被当数据；读 Parquet 更快：`df = spark.read.parquet("/tmp/data.parquet")`，它自动识别 schema，无需手写。`show(10, truncate=False)` 是调试利器，`truncate=False` 防止长文本被截成 `...`；`df.printSchema()` 看字段类型是否推断正确（比如把数字当字符串）；`df.count()` 触发真正计算，别以为 `df.show()` 就执行了全量扫描——它默认只拉前 20 行。最后，`spark.stop()` 要放在 `try...finally` 块里，确保异常时也能释放资源。我有个习惯：每次实验结束前，顺手打开 http://localhost:4040，看 Executors 页面确认 driver 是否已退出，Active Jobs 是否为空。这才是本地实验闭环的终点。 ## 6. 从本地模式平滑过渡到伪分布式集群 当你发现 `local[*]` 处理 1GB 数据太慢，想试试多进程并行，又不想折腾真集群，伪分布式（pseudo-distributed）是最优解。它本质是：在同一台机器上，用不同 JVM 进程分别跑 master、worker、driver，网络通信走 localhost，完全复现集群行为。第一步，进 `$SPARK_HOME/conf`，把 `spark-env.sh.template` 复制为 `spark-env.sh`，填入： ```bash export JAVA_HOME=/opt/java/jdk-17.0.2 export SPARK_MASTER_HOST="127.0.0.1" export SPARK_WORKER_MEMORY="2g" export SPARK_WORKER_CORES="2" ``` 注意 `SPARK_MASTER_HOST` 不能写 `localhost`，某些 DNS 解析会失败，必须用 `127.0.0.1`。第二步，启动 master：`$SPARK_HOME/sbin/start-master.sh`，终端会打印类似 `spark://127.0.0.1:7077` 的 URL；第三步，启动 worker：`$SPARK_HOME/sbin/start-worker.sh spark://127.0.0.1:7077`。打开 http://127.0.0.1:8080，你应该看到一个 Active Workers 和 Running Applications。此时改代码：`SparkSession.builder.master("spark://127.0.0.1:7077")`，再运行，计算就会分发到 worker 进程。你会发现 shuffle 时间变短、task 并行度提升，但总耗时未必快——因为单机磁盘 IO 成了瓶颈。这是好事，它提前暴露了生产环境的典型问题：不是 Spark 不行，是数据源或存储格式拖了后腿。伪集群的价值不在提速，而在验证你的代码能否跨 JVM 正常序列化、能否处理分区倾斜、能否在 driver 与 executor 间稳定传参。我建议每个新项目上线前，都用伪集群跑一遍全链路，比等上生产再炸锅强十倍。