DBFS存储的Python项目如何实现标准模块导入替代addPyFile

DevOps 小满

2026-8-28

解决方案

不需要强制使用addPyFile()实现模块加载，完全可以复刻标准Python环境的导入机制，你遇到的导入报错核心原因是Python解释器启动时，没有将项目根目录/dbfs/src纳入模块搜索路径列表sys.path，和包结构本身没有关系。

方案1：代码内注入搜索路径（改动最小）

在main.py的最顶部、所有自定义模块导入语句之前，添加如下代码，将项目根目录加入Python模块搜索路径：

import sys
# 声明项目根目录的本地挂载路径
PROJECT_ROOT = "/dbfs/src"
if PROJECT_ROOT not in sys.path:
    sys.path.append(PROJECT_ROOT)

# 后续直接使用标准导入语法即可，和本地部署的写法完全一致
from common import util

这个写法和本地运行Python项目时手动把项目根目录加入PYTHONPATH的逻辑完全一致，支持任意层级的包结构、多模块互相导入，不需要逐个文件加载依赖。

方案2：运行时配置环境变量（无代码侵入，生产推荐）

如果不想修改业务代码，可以在Azure Data Factory的Python活动配置中，新增环境变量PYTHONPATH，值设置为/dbfs/src，Python解释器启动时会自动把该路径加入模块搜索目录，全程不需要改动任何业务代码的导入逻辑，和本地部署时配置系统环境变量的标准操作完全一致。

关于`addPyFile()`的说明

spark.SparkContext.addPyFile()是Spark提供的分布式依赖分发方法，作用是把指定的Python文件同步到所有Executor节点的工作目录，仅在需要把依赖分发到分布式计算节点运行的时候才需要使用。
这个方法不会识别多层级的Python包结构，如果你项目里有多层子包、模块间存在互相依赖，用这个方法需要逐个添加所有.py文件，维护成本极高，不适合作为常规本地包导入的替代方案。