本文详解如何通过 pip install -e . 正确安装本地 python 项目，并使其自动识别嵌套子包（如 mypkg.subpkg1），关键在于正确设置 package_dir 映射与 find_packages() 的配合使用。
在采用“ad-hoc 布局”（即源码目录不与包名同名，例如顶层为 project_root/，实际包位于 project_root/mypkg/）的本地 Python 项目中，直接使用 pip install -e . 往往无法正确导入子模块——即使所有 __init__.py 文件齐全、路径结构合规。典型症状包括：find_packages() 报错 package directory 'subpkg1' does not exist，或虽安装成功但 import mypkg.subpkg1 失败。
根本原因在于：find_packages() 默认在当前目录（.）下搜索带 __init__.py 的包，而你的包实际位于 mypkg/ 子目录中。若未显式声明源码根目录映射，setuptools 会错误地将 mypkg/subpkg1 解析为相对于项目根的 ./subpkg1，从而导致路径查找失败。
✅ 正确解法是：同时配置 package_dir 和 find_packages()，明确告知 setuptools “包逻辑名称” 与 “物理路径” 的对应关系：
# setup.py
from setuptools import setup, find_packages
setup(
name="Code",
author="Me",
author_email="Me",
description="Code",
package_dir={"": "mypkg"}, # ✅ 关键：空字符串 "" 表示根包名（即 mypkg），映射到 ./mypkg/
packages=find_packages(where="mypkg"), # ✅ 在 mypkg/ 下递归发现所有子包
python_requires=">=3.6",
)? package_dir={"": "mypkg"} 的含义是：所有未显式命名的包（即顶层包 mypkg 及其全部子包）均从 mypkg/ 目录下加载。这使 find_packages(where="mypkg") 能正确遍历 mypkg/subpkg1/、mypkg/subpkg2/ 等真实路径。
安装后验证：
立即学习“Python免费学习笔记（深入）”；
pip install -e .
python -c "from mypkg.subpkg1 import module1; print('Success!')"⚠️ 注意事项：
- 不要混用 setup.py 和 pyproject.toml 中的构建配置：若已存在 pyproject.toml（尤其含 [build-system]），优先推荐迁移到现代声明式配置（见下方替代方案）；
- IDE 自动补全可能滞后：如 VS Code 或 PyCharm 未立即识别新包结构，重启语言服务器或重新加载工作区即可解决（非代码问题，属环境缓存）；
- __init__.py 缺失 = 非包目录：确保每个希望被导入的子目录（如 subpkg1/）均含 __init__.py（可为空），否则 find_packages() 会跳过它；
- 现代推荐（Python 3.8+）：可改用 pyproject.toml 实现等效配置，更简洁且符合 PEP 517/518 标准：
# pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"
[project]
name = "Code"
authors = [{name = "Me", email = "Me"}]
description = "Code"
requires-python = ">=3.6"
[project.urls]
Homepage = "https://example.com"
[tool.setuptools]
package-dir = {"" = "mypkg"} # 等效于 setup.py 中的 package_dir
packages = {find = {where = ["mypkg"]}} # 等效于 find_packages(where="mypkg")至此，执行 pip install -e . 即可完成可编辑安装，所有 mypkg.* 子模块均可直接导入与使用，真正实现“一次配置，全树可见”。
