如何调试开发中的Python包 解决test.py运行时相对导入报错问题

你遇到的报错本质是：直接用python test.py运行单个脚本时，Python会将test.py所在的目录设为执行上下文根目录，且该脚本会被识别为__main__顶层模块，不被视作任何包的组成部分，因此不支持相对导入语法（带.的导入语句）。除此之外你写的相对导入路径也和实际文件结构不匹配，你的module.py存放在PackageName目录下，不存在src层级，就算相对导入生效也会找不到目标模块。

方案1：可编辑安装（最推荐，Python包开发标准实践） #

这个方案可以让你直接导入本地正在开发的包代码，修改后无需重新安装即可生效，完全不需要修改导入逻辑和系统路径：

• 首先确保你的项目根目录（即MyPackage文件夹，内部包含PackageName子文件夹）下有包配置文件，最简单的可以新建pyproject.toml，写入基础配置：

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

[project]
name = "PackageName"
version = "0.1.0"
packages = ["PackageName"]

• 在MyPackage根目录下打开终端，执行命令：
  pip install -e .
• 此时你就可以在test.py中直接写绝对导入语句：
  from PackageName.module import SomeClass
• 直接运行python test.py即可调用本地最新的代码，不会用到系统中已安装的旧版本。

方案2：临时修改Python路径（无需修改配置，适合临时调试） #

如果不想安装包，也可以通过将项目根目录临时加入Python导入搜索路径解决：

运行时指定路径 #

• Linux/macOS 终端执行：
  PYTHONPATH=. python test.py
• Windows CMD 执行：
  set PYTHONPATH=. && python test.py
• Windows PowerShell 执行：
  $env:PYTHONPATH="."; python test.py

代码内修改路径 #

也可以在test.py的最开头加入以下代码，自动添加上下文路径：

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.resolve()))

修改完成后直接运行python test.py即可正常导入。

方案3：标准化测试架构（适合长期维护的项目） #

如果是长期维护的Python包，建议调整为行业通用的项目结构，配合测试框架使用：

• 调整后结构参考：

MyPackage/
├── pyproject.toml
├── src/
│   └── PackageName/
│       ├── __init__.py
│       └── module.py
└── tests/
    └── test_module.py

• 安装测试框架pytest：pip install pytest
• 完成可编辑安装后，直接在MyPackage根目录执行pytest命令，框架会自动发现所有测试文件并执行，不需要手动处理导入路径问题。

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