Sphinx中“No module named 'helpers'”错误的解决方法

问题分析 #

报错核心是Sphinx的autodoc工具在导入src.create_alias模块时，找不到依赖的helpers模块。原因主要有两个：一是Python模块搜索路径没正确配置，二是代码中的导入写法不符合规范。

步骤1：修正conf.py的sys.path配置 #

假设你的conf.py在project-1/docs/目录下（Sphinx配置文件的常规位置），把项目的src目录添加到Python的模块搜索路径里，替换现有sys.path代码为：

import os
import sys
# 动态获取src目录的绝对路径并加入搜索路径
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src')))

这种写法能避免硬编码路径的问题，无论docs目录结构怎么变，都能准确定位到src目录。

步骤2：检查代码中的导入写法 #

打开src/create_alias/create_alias.py，调整导入helpers的代码：

• 用相对导入（推荐，符合包内模块引用规范）：

  # 从当前create_alias包下导入helpers模块
  from .helpers import helper
  

• 用绝对导入（基于src作为根模块）：

  # 从src.create_alias包下导入helpers模块
  from src.create_alias.helpers import helper
  

注意：create_alias和helpers文件夹下都要有__init__.py文件（空文件即可），确保它们被识别为Python包。

步骤3：验证导入有效性 #

在project-1根目录激活虚拟环境后，执行以下命令测试模块导入是否正常：

python -c "from src.create_alias import create_alias"

如果没有报错，说明路径配置正确，再重新运行Sphinx生成文档：

cd docs
make html

额外注意事项 #

• 不要在sys.path中添加重复或无效的路径，保持配置简洁
• 确保helpers文件夹下的__init__.py存在，哪怕是空文件也能让Python识别它为包

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