使用Gunicorn部署Flask应用时遇ModuleNotFoundError问题求助

问题原因 #

Flask命令和Gunicorn启动时对Python模块搜索路径（sys.path）的处理逻辑不同：

• 当使用flask --app main.py run时，Flask会自动将main.py所在目录的父目录（即包含app文件夹的项目根目录）添加到sys.path中。此时Python能识别app作为顶层包，所以from app.api.v1 import v1这类导入语句可以正常工作。
• 而使用Gunicorn执行gunicorn --workers=3 main:application时（假设你在app目录下执行），Gunicorn仅将当前工作目录（app目录）加入sys.path。此时Python在sys.path中找不到app包（因为app目录本身就是这个包，它的父目录不在搜索路径里），所以抛出ModuleNotFoundError。

不需要移除app.前缀 #

你的项目采用标准的Python包结构，app作为顶层包，使用from app.XXX import YYY的导入方式符合规范，能保证代码的可维护性和结构清晰。问题出在启动时的路径配置，而非导入语句本身，完全不需要修改导入前缀。

解决方法 #

方法一：在项目根目录执行Gunicorn命令 #

切换到app目录的父目录（项目根目录），执行以下命令：

gunicorn --workers=3 app.main:application

此时项目根目录在sys.path中，Python可以正常识别app包。

方法二：在app目录下修改环境变量后启动 #

如果必须在app目录下执行启动脚本，可以在start.sh中先将项目根目录添加到PYTHONPATH：

# start.sh内容
export PYTHONPATH=$(dirname "$PWD"):$PYTHONPATH
gunicorn --workers=3 main:application

$(dirname "$PWD")会获取app目录的父目录路径，将其加入PYTHONPATH后，Python就能找到app包。

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