Python项目结构的关键在于模块划分逻辑、导入路径控制和包初始化行为，而非教程编号；__init__.py空则标识包，有内容可暴露接口、防循环导入或触发副作用；PYTHONPATH优先级高于sys.path但不推荐使用；tests/应与主包同级并排除在安装外。
这标题不是学习路线，是营销包装——Python 项目结构没有“第238讲”这种官方分级，也没有统一教程编号。真正决定项目是否可维护的，是模块划分逻辑、导入路径控制和包初始化行为，不是讲数。
为什么 __init__.py 有时为空，有时必须写内容？
空的 __init__.py 只起标识作用，让 Python 把目录当成包；但一旦需要控制包的公共接口、设置默认导入或执行初始化逻辑，就必须写内容。
- 暴露子模块：在
mylib/__init__.py中写from .core import process_data，调用方才能直接from mylib import process_data - 避免循环导入：把跨模块共享的常量或类型定义提前放到
__init__.py，比分散在各模块里更可控 - 触发副作用：某些库（如旧版 Flask 扩展）依赖
__init__.py中的注册语句，删掉就失效
sys.path 和 PYTHONPATH 哪个优先级更高？
PYTHONPATH 环境变量的内容会被插入到 sys.path 开头，所以它优先级更高——但这不等于推荐使用。
- 本地开发时设
PYTHONPATH=.:./src能绕过安装，但 CI 环境通常没配，导致“本地能跑线上报ModuleNotFoundError” -
pip install -e .是更可靠的方式：它把当前项目路径写进site-packages的.pth文件，既生效又可复现 - 检查实际导入路径：运行
python -c "import mymodule; print(mymodule.__file__)"，比猜sys.path顺序更直接
测试目录 tests/ 放哪才不会导入冲突？
放在项目根目录下（与 src/ 或主包同级），并确保测试代码不被当作包安装——这是最简且兼容性最好的方式。
- 不要把
tests/放进主包里（如mylib/tests/），否则pip install会把它一起装进去，还可能意外被pytest发现为测试包 -
pyproject.toml中加packages = [{include = "mylib"}]，明确排除tests/
- 运行测试时用
pytest tests/，而不是python -m pytest tests/—— 后者可能改变工作目录导致相对导入失败
pyproject.toml
[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "mylib"
version = "0.1.0"
packages = [{include = "mylib"}]
项目结构的关键不在层级多深，而在每个 import 是否清晰表达意图、每次 pip install 是否产生预期结果。那些靠改 sys.path 硬凑出来的结构，上线前一定会在某个环境里崩一次。
