PYTHONPATH配置正确 GitLab CI运行仍报ModuleNotFoundError

所有配置看似无误，相同代码在本地机器可正常运行，但在GitLab CI环境中执行时报错，最初怀疑执行pip install -r $CI_PROJECT_DIR/scripts/config_creator/requirements.txt步骤对环境造成了异常影响。

GitLab CI 阶段配置 #

Clone Siteconfigs:
  stage: configure-site
  script:
    - echo $PYTHONPATH
    - apt-get update --yes
    - apt-get install --yes  python3-pip
    - python3 --version
    - pip install -r $CI_PROJECT_DIR/scripts/config_creator/requirements.txt
    - echo $PYTHONPATH
    - export PYTHONPATH=$CI_PROJECT_DIR
    - echo $PYTHONPATH
    - python3 -c "import sys; print(sys.path)"
    - python3 $CI_PROJECT_DIR/scripts/config_creator/__main__.py create-loadtest-config-file --dataset-uri-list ${LOADTEST_SOURCES_DATASET_URI_LIST}

GitLab CI 运行输出 #

$ echo $PYTHONPATH
/builds/qa/load-test-ci
$ python3 -c "import sys; print(sys.path)"
['', '/builds/qa/load-test-ci', '/usr/lib/python39.zip', '/usr/lib/python3.9', '/usr/lib/python3.9/lib-dynload', '/usr/local/lib/python3.9/dist-packages', '/usr/lib/python3/dist-packages']
$ python3 $CI_PROJECT_DIR/scripts/config_creator/__main__.py create-loadtest-config-file --dataset-uri-list ${LOADTEST_SOURCES_DATASET_URI_LIST}
Traceback (most recent call last):
  File "/builds/qa/load-test-ci/scripts/config_creator/__main__.py", line 1, in <module>
    from scripts.config_creator.cli.main import main
ModuleNotFoundError: No module named 'scripts.config_creator'

main.py 代码内容 #

from scripts.config_creator.cli.main import main

if __name__ == '__main__':
    main()

该问题与pip安装依赖的步骤无关，是Python运行脚本的默认路径处理规则导致的：

• 执行python3 -c "import sys; print(sys.path)"时，未指定具体脚本文件，sys.path第一个条目为空字符串，对应当前工作目录（即项目根目录/builds/qa/load-test-ci），此时打印的路径符合预期。
• 当直接执行python3 /full/path/to/script.py时，Python会自动将脚本所在的父目录（本场景中为/builds/qa/load-test-ci/scripts/config_creator/）插入sys.path的最高优先级位置，替换掉原有的当前工作目录条目。
• 代码中导入的scripts.config_creator模块需要从项目根目录开始查找，但此时sys.path优先级最高的是config_creator目录，该目录下不存在scripts子目录，因此触发模块找不到的错误。
• 本地运行正常是因为本地运行时通常在项目根目录使用模块方式启动，或是IDE自动配置了运行时路径，未触发上述路径替换逻辑。

使用Python模块运行方式替换原有的直接指定脚本路径的命令，将CI步骤中最后一行执行脚本的命令修改为：

python3 -m scripts.config_creator create-loadtest-config-file --dataset-uri-list ${LOADTEST_SOURCES_DATASET_URI_LIST}

-m参数会让Python从sys.path包含的路径中查找对应模块，此时已配置的PYTHONPATH包含项目根目录，可以正确定位scripts.config_creator包，完成导入。

内容的提问来源于stack exchange，提问作者Ahmet Karakaya