直接说结论：本地VSCode调试能跑的PySpark代码，一提交到集群就报ModuleNotFoundError，根源只有一个——Executor进程压根没加载你写的自定义模块。这个问题和IDE配置、Python解释器路径都没关系，真正管用的解法就两条：spark-submit --py-files或者spark.sparkContext.addPyFile()。

PySpark调试时Executor找不到自定义模块怎么办

先说最核心的一点。你写的import my_utils，在本地开发环境里能跑通，是因为Driver进程能访问到你本地的Python环境。

但一旦切换到集群模式，Executor是在工作节点上启动的全新Python进程，它根本不知道你的my_utils模块在哪儿。VSCode本地调试器能跑通，不代表集群能跑。这是很多人最容易踩的坑。

关键不是“怎么让VSCode调试起来”，而是“怎么让Executor真正拿到你的代码”。spark-submit --py-files或addPyFile()是唯一可靠路径。IDE的Python解释器配置，比如选对conda env，只影响Driver端，对Executor完全无效。

正确处理方式

具体做法并不复杂，但有几个细节必须到位：

• 把所有非标准库的Python模块打包成.zip文件，注意是.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构建SparkContext，必须在getOrCreate()方法调用之前，先执行spark.sparkContext.addPyFile("utils.zip")。否则一旦Driver启动完毕，再添加文件就晚了。

简单说，包得在Driver启动前就准备好，就像客人来了你才想起来买菜，来不及的。

为什么在VSCode里设PYSPARK_PYTHON没用

很多人会在VSCode的启动配置里，或者环境变量里设置PYSPARK_PYTHON，指望这样能让Executor统一用同一个Python解释器。

想法挺好，但PYSPARK_PYTHON这个参数实际上只控制Driver进程用哪个Python解释器。Executor那边，它会默认使用集群节点上PATH里面的python，也就是集群自带的那个Python，通常不是你本地conda环境或者虚拟环境里的那个。

所以你在VSCode里激活了pyspark环境，Driver能正常import，但Executor报ModuleNotFoundError是必然结果。

真正统一Python环境的方式

要真正统一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等闭包函数，VSCode完全无法单步调试。PySpark目前不支持跨进程的Python调试，这是一个硬伤。

可行的替代方案

所以替代方案非常有限，基本就两条路：

• 在闭包函数里加上print()或logging.info()，输出到Executor的日志里。YARN模式下可以用yarn logs -applicationId xxx来查看。虽然麻烦，但这是最直接的调试手段。
• 把核心逻辑抽成纯函数，然后在本地用pytest来写单元测试。确保这些函数不依赖SparkContext或任何外部状态，这样在本地就能把逻辑验证清楚。
• 一个实用的建议：尽量避免在闭包里写复杂逻辑。把数据处理步骤拆到Driver端预处理，闭包里的代码尽量精简，这样出错概率也会降低。

这确实是个局限，但理解了这个原理，至少不会在集群模式下对着断点干瞪眼了。

PyFiles分发后仍报ImportError的典型原因

很多时候不是配置文件写错了，也不是路径有问题，而是ZIP包内部的结构不对。

PySpark对.zip文件内部结构有严格的要求：必须是一个可以直接import的模块结构，而且不能包含顶层的__pycache__或.pyc文件。

先做一个最简单的验证

最简单的验证方式：解压你的ZIP包，然后在命令行里试试python -c "import my_utils"。

• 如果能成功，集群上大概率也能跑通。
• 如果失败，那集群上一定会报错。

常见错误结构案例

• 正确结构：utils.zip/my_utils/__init__.py——这是最规范的。
• 错误结构：utils.zip/src/my_utils/__init__.py——多了src这一层，PySpark会无法定位模块，直接报错。
• 错误结构：utils.zip/my_utils.pyc——注意，PySpark不加载.pyc文件，而且不同Python版本的字节码可能不兼容，会导致更隐蔽的错误。
• 不要贪图省事，直接zip -r整个项目根目录。这样很容易带入一堆无关文件，比如.git文件夹、本地测试数据、IDE配置文件等等，既增加传输负担，也可能引发奇怪的问题。

更稳妥的打包方式

最稳妥的做法是：新建一个干净的目录，只把你需要分发的模块放进去，然后再执行打包。

任何“看起来差不多”的结构，都可能在集群上静默失败，到时候排查起来更费劲。