本地正常的Flask项目为何在远程服务器出现Python相对导入错误

我在本地Ubuntu机器和远程Ubuntu服务器上使用完全相同的终端命令启动Flask服务器：

virtual venv
source venv/bin/activate
pip install flask flask_cors gunicorn #... 以及其他依赖
FLASK_DEBUG=1 FLASK_APP=server flask run --host=0.0.0.0

本地执行flask run完全正常，但远程服务器执行时抛出错误：

...
  File "/root/foo/src/server.py", line 31, in create_app
    from .bar import bar_blueprint
ImportError: attempted relative import with no known parent package

本地机器环境：

• Ubuntu 22.04.2
• Python 3.10.6

(venv) gv@dev:~/foo/src$ python
Python 3.10.6 (main, Mar 10 2023, 10:55:28) [GCC 11.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

远程服务器环境：

• Ubuntu 22.10
• Python 3.10.7

(venv) root@server:~/foo/src# python
Python 3.10.7 (main, Mar 10 2023, 10:47:39) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

这个问题的核心是Python模块导入上下文的差异，尽管本地和远程Python版本接近，但启动时的工作目录、模块识别逻辑的细微差别导致相对导入失效。

可能的原因： #

• 工作目录差异：本地启动时工作目录可能是~/foo/（src的父目录），而远程服务器在~/foo/src/下执行命令。直接以FLASK_APP=server启动时，Python会把server.py当作独立脚本运行，而非src包的一部分，相对导入.bar找不到父包。
• PYTHONPATH配置差异：本地环境的PYTHONPATH默认包含当前工作目录的父目录，或之前有相关配置，远程服务器没有，导致无法识别src为有效包。
• 用户环境隐性差异：远程用root用户，本地用普通用户，不同用户的Python环境变量（如PYTHONPATH）默认配置不同。

解决方案： #

1. 调整工作目录启动

切换到src的父目录~/foo/后执行启动命令：

cd ~/foo/
FLASK_DEBUG=1 FLASK_APP=src.server flask run --host=0.0.0.0

此时Python会将src识别为合法包，相对导入可正常解析。

2. 临时设置PYTHONPATH

无需切换目录，启动时将当前目录的父目录加入Python路径：

cd ~/foo/src/
PYTHONPATH=../ FLASK_DEBUG=1 FLASK_APP=server flask run --host=0.0.0.0

3. 改用绝对导入

修改server.py中的导入语句为基于项目根目录的绝对导入：

from src.bar import bar_blueprint

这种方式更稳定，能避免不同环境下的路径问题。

4. 显式添加包标识文件

在src目录下创建空的__init__.py文件，明确告知Python这是一个包目录。尽管Python 3.3+支持命名空间包，但显式添加该文件可消除环境间的隐性差异。

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