首先得帮你理清几个核心概念，你之前的困惑大多来自对Python导入机制和__init__.py作用的误解：

为什么你之前的导入会失败？ #

当你在project_package/目录下直接运行python process.py时，Python会把**当前工作目录（也就是project_package/）**加入sys.path的最前端，而不是它的父目录repo_dir/。这就导致：

• 直接import config能成功：因为config.py就在当前目录（sys.path里的路径）；
• import project.config或from project import config失败：因为Python在sys.path里找不到project这个包（它在repo_dir/下，但repo_dir/不在sys.path里）。

至于__init__.py，它的作用只是告诉Python「这个目录是一个可导入的Python包」，它不会自动把父目录加入sys.path——这是你之前的核心误解点。

你的问题逐一解答 #

1. 正确的Python库搭建方式 #

你的现有结构已经很接近标准了，只需要调整使用逻辑：

repo_dir/
├── project_package/  # 这是你的核心包目录
│   ├── __init__.py   # 标记为Python包，空文件也可以
│   ├── process.py
│   └── config.py
└── tests/            # 测试目录，建议单独放
    └── test_process.py

2. 推荐的导入方式 #

分两种场景：

场景一：包内部模块互相导入（比如process.py调用config.py）

推荐用相对导入，这种方式不依赖sys.path，只针对当前包内部：

# process.py
from . import config
print(config.name)

如果是多层目录，还可以用from ..subpackage import module的形式，非常灵活。

如果偏好更清晰的绝对路径，也可以用绝对导入，但前提是repo_dir/在sys.path里：

# process.py
from project_package import config
print(config.name)

场景二：外部脚本/测试导入你的包

比如在tests/test_process.py里导入，同样用绝对导入，只要repo_dir/在sys.path里即可。

3. __init__.py的正确位置 #

你现在的位置完全正确：每个需要作为Python包的目录下都要放一个__init__.py（哪怕是空文件）。除了标记目录为包，它还能做这些事：

• 导出包内常用模块/变量，让用户更方便地导入：

  # project_package/__init__.py
  from .config import name
  from .process import core_function
  

  这样用户导入时可以直接写import project_package，然后用project_package.name、project_package.core_function；
• 定义包级别的初始化逻辑，比如加载配置、初始化资源等。

4. 要不要每个项目都手动加sys.path？ #

绝对不推荐把修改sys.path作为常规操作，这会让你的代码依赖特定目录结构，移植性极差。更好的替代方案有两个：

方案一：用模块模式运行脚本

不要在project_package/目录下直接跑python process.py，回到repo_dir/，用下面的命令运行：

python -m project_package.process

-m参数会让Python以模块的方式运行，自动把repo_dir/加入sys.path，这样你的绝对导入就能正常工作了。

方案二：把包安装到Python环境

如果这是一个可复用的库，推荐写一个setup.py（放在repo_dir/下）：

from setuptools import setup, find_packages

setup(
    name="project_package",
    version="0.1.0",
    packages=find_packages(),
)

然后在repo_dir/下运行：

pip install -e .

-e是开发模式，修改代码后不需要重新安装。安装完成后，不管你在哪个目录，都能直接import project_package，完全不需要关心sys.path。

5. 为什么Python导入看起来这么复杂？ #

其实核心逻辑很简单：Python的导入是基于sys.path里的路径去查找包和模块的。这种设计给了极大的灵活性——你可以把包放在任何位置，只要加入sys.path就能导入，但对新手来说，容易因为工作目录、包结构的差异导致导入失败。

总结一下最佳实践 #

• 包内部用相对导入，避免依赖sys.path；
• 运行脚本用python -m 包名.模块名，或者安装包后运行；
• __init__.py放在每个包目录下，按需导出内容；
• 尽量不要手动修改sys.path，除非是临时调试场景。

内容的提问来源于stack exchange，提问作者T. Brian Jones