Python模块导入冲突：如何兼容直接运行与测试导入场景？

这个问题本质是Python的模块搜索路径冲突导致的：

• 直接运行python3 app.py时，Python会把src/main目录加入搜索路径，所以import constants能找到同目录下的文件；
• 但从test_commands.py导入app时，Python的搜索路径是src或项目根目录，此时constants.py不在搜索路径里，自然找不到；反过来用from main import constants时，直接运行app.py又找不到main包，因为此时搜索路径里没有src。

下面是几种能让两种场景都正常工作的方案：

方案1：相对导入 + 模块方式运行脚本 #

在app.py里把导入语句改成相对导入：

from . import constants

两种场景的运行方式调整：

• 直接运行app.py时，不能用python3 app.py，要从src目录下执行：

  python -m main.app
  

• 测试模块test_commands.py里的from main import app可正常使用，只要运行测试时保证src在搜索路径里（比如从项目根目录project下运行测试脚本）。

方案2：手动添加src目录到搜索路径 #

在app.py的最顶部添加代码，把src目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取当前文件的父目录（main）的父目录（src）
src_dir = Path(__file__).resolve().parent.parent
if str(src_dir) not in sys.path:
    sys.path.append(str(src_dir))

之后app.py里就可以用绝对导入：

from main import constants

这样不管是直接运行python3 app.py，还是测试模块导入app，都能正常找到constants模块——因为src被加入了搜索路径，main包能被识别，constants也能通过main包找到。

方案3：转为可安装包（长期项目推荐） #

在project目录下创建pyproject.toml文件，内容示例：

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

[project]
name = "myproject"
version = "0.1.0"
packages = ["main"]
package_dir = {"": "src"}

然后在项目根目录执行pip install -e .，把项目以可编辑模式安装到Python环境里。

之后不管是app.py里用from main import constants，还是测试模块导入app，都能正常工作——因为main包已经被Python识别为全局可导入的包了。

此类场景的正确导入方式 #

优先使用绝对导入（比如from main import constants），配合保证项目的根目录（或src目录）在Python的模块搜索路径中。小型项目用方案2足够解决问题；长期维护的项目，方案3的可安装包方式更规范，能避免各种导入问题。

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