PyPI可安装Python项目的正确导入配置问题

你遇到的导入错误核心是package_dir配置写错了。
你当前配置的package_dir: {"": "project_x"}，本质是告诉setuptools：setup.py所在目录下的内层project_x文件夹，是存放所有顶级Python包的根目录。这就导致打包工具会直接把pack_a、pack_b识别为独立的顶级包，而不是project_x包下的子模块。
这种错配下，mod_a1.py里写的from pack_a.mod_a2 import something能运行只是巧合——此时pack_a本身就是顶级包，当然能直接导入。但mod_b.py里写的from ..pack_a.mod_a import ...会失败就很合理：pack_b自己已经是顶级包了，向上跳一级（两个点代表父级包）就直接跳出了所有包的层级范围，自然触发attempted relative import beyond top-level package报错。

优先选第一种标准方案，是PyPI发布项目的通用规范，踩坑概率最低。

方案1：修正打包配置，统一使用绝对导入（官方推荐） #

1. 直接删掉setup.py里错误的package_dir配置项，默认以setup.py所在目录作为包搜索根目录即可。
2. 修正setuptools的包发现逻辑，明确识别内层project_x为项目的顶级包，示例配置：

   from setuptools import setup, find_packages
   
   setup(
       name="project_x",
       # 省略版本、作者、README等元信息配置
       packages=find_packages(include=["project_x", "project_x.*"]),
   )
   

3. 把项目内所有跨模块导入统一改成从顶级包名project_x开始的绝对路径导入：
   • mod_a1.py中原来的from pack_a.mod_a2 import something改为from project_x.pack_a.mod_a2 import something
   • mod_b.py中原来的跨包导入直接写from project_x.pack_a.mod_a import xxx即可
     这种写法兼容性最好，不管是开发阶段用pip install -e .做可编辑安装，还是打包上传PyPI后用户正式安装，导入逻辑都完全一致，不会出现本地跑通、安装后报错的问题。

方案2：保留相对导入的适配方式（不推荐） #

如果你习惯用相对导入，不需要改所有导入语句，只要修正打包配置即可：

1. 和方案1一致，删掉错误的package_dir，正确配置find_packages让工具识别project_x为顶级包。
2. 调整相对导入的层级和实际包结构匹配：
   • 同包内导入，比如mod_a1.py导入同目录的mod_a2.py，写from .mod_a2 import something（单个点代表当前包目录）
   • 跨子包导入，比如pack_b/mod_b.py导入pack_a下的模块，原来写的from ..pack_a.mod_a import xxx是可以正常运行的——此时pack_b的父级是顶级包project_x，两个点刚好回到顶级包层级，不会再触发超出顶级包的报错。

注意：Python的相对导入有固有机制限制，只有当模块作为包的一部分被导入时才能正常运行。如果你直接用python project_x/pack_b/mod_b.py这种方式单文件执行脚本，相对导入依然会报错，没有打包配置可以绕过这个限制。

• 不要为了迁就某一处写错的导入随意修改package_dir，这个配置的作用是建立包名和文件系统路径的映射关系，错配会直接打乱整个项目的包层级。
• 不需要刻意禁用相对导入，但公开发布到PyPI的项目更推荐用全路径绝对导入，排查问题时可以直接看到导入的完整链路，不会因为模块移动位置混淆层级。
• 本地开发时不要直接把内层源码目录加到PYTHONPATH里跑测试，这种方式和正式安装后的包结构不一致，很容易出现本地正常、安装后导入失败的问题，统一用pip install -e .做可编辑安装最稳妥。

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