GitHub Actions中使用pdoc生成文档遇ModuleNotFoundError求助

问题根源 #

GitHub Actions的Python运行环境默认不会把当前工作目录加入sys.path，而本地环境通常已经包含该路径，这就导致本地能正常运行但CI环境报错。

修复方案 #

1. 临时设置PYTHONPATH（快速解决） #

修改你的GitHub Actions脚本，在执行pdoc或测试命令前，把当前目录添加到环境变量：

- name: 生成文档
  run: |
    export PYTHONPATH="$PYTHONPATH:."
    pdoc mainFile.py -o docs

2. 使用模块方式运行命令 #

运行测试时，用python -m pytest代替直接调用pytest，这会自动将当前目录加入Python的搜索路径：

- name: 运行单元测试
  run: python -m pytest test_mainFile.py -v

如果是测试文件本身的问题，也可以在test_mainFile.py开头添加以下代码手动添加路径：

import sys
from pathlib import Path
sys.path.append(str(Path(__file__).parent))

import mainFile

3. 调整为标准包结构（长期维护推荐） #

把项目改成可安装的包结构，这样无论本地还是CI环境都能正常导入：

你的项目/
├── src/
│   └── mainFile.py
├── tests/
│   └── test_mainFile.py
└── pyproject.toml

在pyproject.toml中添加基础配置：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
version = "0.1.0"
packages = ["src"]

然后在GitHub Actions中先安装包再执行命令：

- name: 安装项目
  run: pip install -e .

- name: 生成文档
  run: pdoc src.mainFile -o docs

- name: 运行测试
  run: python -m pytest tests/test_mainFile.py -v

验证 #

修改后重新触发GitHub Actions，确认ModuleNotFoundError是否消失，同时保证本地运行依然正常。

内容的提问来源于stack exchange，提问作者Filip Z