根本原因是executor进程未加载自定义模块；必须通过spark-submit --py-files或spark.sparkcontext.addpyfile()将模块打包为.zip（结构合规、无__pycache__）分发至集群，而非依赖本地ide配置。
PySpark调试时Executor找不到自定义模块怎么办
根本原因是：本地开发时写的 import my_utils，在集群模式下，Executor 启动的 Python 进程根本没加载这个模块。VSCode 本地调试器能跑通，不代表集群能跑——这是最常踩的坑。
关键不是“怎么让 VSCode 调试起来”，而是“怎么让 Executor 真正拿到你的代码”。spark-submit --py-files 或 addPyFile() 是唯一可靠路径，IDE 的 Python 解释器配置（比如选对 conda env）只影响 Driver 端，对 Executor 无效。
- 把所有非标准库的 Python 模块打包成
.zip（不能是文件夹），例如zip -r utils.zip my_utils/ tests/ __init__.py - 提交时显式带上：
spark-submit --py-files utils.zip --master yarn app.py（YARN）或--master spark://xxx（Standalone） - 如果用
SparkSession.builder构建，必须在getOrCreate()之前调用spark.sparkContext.addPyFile("utils.zip")，否则 Driver 已启动，再加也无效
为什么在 VSCode 里设 PYSPARK_PYTHON 没用
PYSPARK_PYTHON 只控制 Driver 进程用哪个 Python 解释器，而 Executor 默认用集群节点上 PATH 里的 python——通常不是你本地 conda 或 venv 里的那个。你在 VSCode 里激活了 pyspark 环境，Driver 能 import 成功，但 Executor 报 ModuleNotFoundError 是必然结果。
真正要统一 Python 环境，得靠集群级分发：
- YARN 上用
--conf spark.yarn.appMasterEnv.PYSPARK_PYTHON=... --conf spark.executorEnv.PYSPARK_PYTHON=...，路径必须是集群节点上真实存在的绝对路径（如/opt/conda/envs/pyspark/bin/python） - Standalone 模式需提前在每台 Worker 节点部署相同 Python 环境，并确保
spark-env.sh中设置了export PYSPARK_PYTHON=... - 别指望
pip install -e .或 VSCode 的 “Python: Select Interpreter” 能透传到 Executor
本地调试（local[*]）和集群模式的断点行为差异
VSCode 断点在 local[*] 模式下能停住所有逻辑，是因为 Driver 和 Executor 在同一个 JVM+Python 进程里；但切到集群模式后，断点只对 Driver 代码生效，Executor 里的 map、filter 等闭包函数完全无法单步——PySpark 不支持跨进程 Python 调试。
替代方案只有两种：
- 在闭包里加
print()或logging.info()，输出到 Executor 日志（YARN 上用yarn logs -applicationId xxx查） - 把核心逻辑抽成纯函数，写单元测试，在本地用 pytest 验证，确保它不依赖 Spark Context 或外部状态
- 避免在闭包里写复杂逻辑；把数据处理步骤拆到 Driver 端预处理，减少闭包体积
PyFiles 分发后仍报 ImportError 的典型原因
不是路径写错，而是 ZIP 包结构不对。PySpark 要求 .zip 内部必须是模块可导入结构，且不能有顶层 __pycache__ 或 .pyc 文件。
验证方式：解压 ZIP，确认你能直接 python -c "import my_utils" 成功；如果失败，集群必然失败。
- 错误结构：
utils.zip/my_utils/__init__.py→ 正确 - 错误结构：
utils.zip/src/my_utils/__init__.py→ 错误，src层级会阻断 import - 错误结构：
utils.zip/my_utils.pyc→ 错误，PySpark 不加载 pyc，且可能因字节码版本不兼容崩溃 - 注意：ZIP 里不要包含
__pycache__目录，也不要用zip -r直接压整个项目根目录（容易带入无关文件）
最稳妥的做法是：新建干净目录，只放你要分发的模块，再 zip。任何“看起来差不多”的结构，都会在集群上静默失败。
