python工程化核心是解决协作与维护中的导入问题：__init__.py缺失、pip install -e .失败、sys.path加载顺序混乱、pythonpath不生效、模块缓存干扰等，需通过-m运行、规范包结构、正确配置pyproject.toml来应对。
Python 工程化不是堆砌工具链，而是让代码在多人协作、持续交付、长期维护中不崩。第269讲这类标题容易让人误以为是“高级技巧合集”，实际它暴露的往往是基础原理没吃透——比如不明白 __init__.py 为何有时可删有时必留，或为什么 pip install -e . 能绕过安装却仍报 ModuleNotFoundError。
为什么 sys.path 和 PYTHONPATH 总对不上？
这是工程化起步阶段最常卡住的地方：本地跑通，CI 失败；IDE 能 import，命令行报错。根本原因不是路径没加，而是加载顺序和模块缓存干扰。
-
sys.path是运行时生效的列表，但 Python 会优先从sys.path[0]（通常是当前目录）开始查，而不是你期望的包根目录 -
PYTHONPATH只影响新启动的解释器，已运行的进程（如 Jupyter kernel、IDE 内置 Python）不会重新读取 -
importlib.invalidate_caches()并不能清掉已成功导入的模块，得用del sys.modules['pkg_name']手动卸载（仅调试用）
实操建议：统一用 -m 方式运行，例如
python -m mypackage.main，强制以包模式启动，避免当前目录污染
sys.path[0]。
setup.py vs pyproject.toml：什么时候必须切？
不是“新版一定更好”，而是构建行为是否被正确捕获。如果你的项目用了 setuptools_scm 自动生成版本号，或需要 build-system.requires 显式声明构建依赖，pyproject.toml 就不可绕过。
-
setup.py在 pip ≥21.3+ 中已被标记为 legacy，某些 CI 镜像默认禁用 -
pyproject.toml中若漏写[project]段，pip install -e .会静默回退到旧逻辑，但不再支持setup.cfg - 混合使用（如
pyproject.toml+setup.py）极易触发未定义行为，官方明确不保证兼容
判断依据：执行
pip debug --verbose，看输出里
build_backend 是否为 setuptools.build_meta 或 hatchling.build —— 若仍是 setuptools.pep517，说明配置未生效。
立即学习“Python免费学习笔记（深入）”；
pip install -e . 报 ModuleNotFoundError 的真实原因
错误信息指向模块名，但问题往往出在包结构本身。典型场景是包内有同名子模块和顶层模块（如 mypackage/mypackage/），或 __init__.py 缺失导致 Python 无法识别为包。
- 检查
find_packages()返回值：在setup.py或pyproject.toml中加一行打印，确认它是否真找到了你的源码目录 - 运行
python -c "import mypackage; print(mypackage.__file__)"
，如果报错，说明没进 editable 模式；如果路径指向site-packages下的 egg-link，说明链接文件损坏，删掉src/同级的.egg-info目录重试 - Windows 下注意路径分隔符：
find_packages(where="src")中的where必须是斜杠或正则安全字符串，反斜杠可能被当成转义
import 失败时，能不能快速区分出是路径问题、缓存问题、包结构问题，还是构建配置没生效。这些边界情况不会出现在“269讲”的演示代码里，但每天都在 PR 和 CI 日志里反复出现。 
