Namespace Packages不可用普通包替代，因其核心价值是允许多个物理目录（如Git子模块、SDK、本地目录）无依赖地共同贡献同一逻辑包名（如myorg.utils），而普通包因__init__.py存在会锁死路径语义，无法自动聚合。
Namespace Packages 为什么不能用普通包替代
普通 Python 包要求存在 <strong>init</strong>.py 文件，一旦出现，就锁死了该路径作为“常规包”的语义。而 Namespace Package 的核心价值在于：多个物理目录可共同贡献同一个逻辑包名，且彼此无源码依赖关系。这在大型项目中很常见——比如 myorg.utils 分散在 Git 子模块、内部 SDK、本地开发目录三个不同路径下，又必须统一导入。
- 如果强行用常规包，你只能选一个
<strong>init</strong>.py所在位置作为“主包”，其余模块得靠sys.path注入或符号链接，一升级就断 - Namespace Package 允许每个子目录各自声明自己是
myorg的一部分，Python 解释器会自动合并它们的子模块 - 注意：从 Python 3.3 起原生支持（PEP 420），无需
<strong>init</strong>.py；3.2 及更早需用pkgutil.extend_path模拟，不推荐
如何正确声明一个 Namespace Package
关键不是写什么代码，而是不写什么：myorg 目录下不能有 <strong>init</strong>.py，哪怕空文件也不行。只要它不存在，且该目录被 Python 的 import 查找机制扫到（比如在 sys.path 中），它就被视为 namespace package 的候选。
- 项目结构示例：
/home/user/proj/ ├── myorg/ │ └── auth/ │ └── __init__.py # 提供 myorg.auth 功能 /home/user/sdk/ ├── myorg/ │ └── db/ │ └── __init__.py # 提供 myorg.db 功能
- 确保两个
myorg目录都在sys.path中（可通过pip install -e /path/to/dir或修改PYTHONPATH实现） - 验证方式：启动 Python，执行
import myorg.auth, myorg.db—— 不报错即生效 - 常见错误：某个
myorg目录下误放了<strong>init</strong>.py，会导致整个 namespace 失效，Python 只认那个带<strong>init</strong>.py的为“真包”，忽略其余
import 时为什么有时找不到跨目录的子模块
这不是 namespace 本身的问题，而是 import 查找路径没对齐。Python 在导入 myorg.auth 时，会依次检查 sys.path 中每个路径下的 myorg/auth/<strong>init</strong>.py；但它不会递归扫描子目录去拼凑模块。
- 确保每个物理
myorg目录都直接位于sys.path条目中，而不是其父目录。例如/home/user/proj在sys.path中，但/home/user/proj/myorg不在，那里面的auth就不会被识别为myorg.auth - 使用
python -c "import sys; print('\n'.join(sys.path))"检查实际路径 - 若用 pip 安装，必须用
-e（editable mode）安装整个含myorg的目录，不能只装子目录 - 还有一个隐形坑：IDE（如 PyCharm）的解释器配置可能和 CLI 不一致，导致编辑器标红但命令行能跑——务必检查 IDE 的 Python interpreter 设置里是否包含了所有相关路径
与 pyproject.toml 和 PEP 517 构建系统的兼容要点
Namespace Packages 本身不依赖构建工具，但现代打包容易踩坑：
立即学习“Python免费学习笔记（深入）”；
-
setuptools61.0+ 默认启用 PEP 420，无需额外配置；旧版需在setup.py中显式声明namespace_packages=['myorg']（已弃用） - 使用
pyproject.toml时，不要写packages = ["myorg"]，因为myorg不是真实包，没有<strong>init</strong>.py，find_packages()会跳过它 - 推荐写法是明确列出真正要打包的子模块：
[project] packages = [ "myorg.auth", "myorg.db", ]
- 如果子模块分散在不同仓库，每个仓库应独立发布自己的
myorg.*包（如myorg-auth==1.2），安装后它们自然聚合到同一 namespace 下——这才是最健壮的协作模式
真正难的不是声明 namespace，而是让所有参与方对“哪个目录该出现在 sys.path”达成一致，并在 CI、容器、IDE、venv 多种环境下保持同步。一个 <strong>init</strong>.py 误触，或一条 PYTHONPATH 遗漏，就足以让整个聚合失效。
