不能把所有代码塞进一个 main.py，因为会导致运行时导入错误、测试无法隔离、依赖难管理、CI/CD 构建失败，最常见的是 ModuleNotFoundError；必须使用 src/ 目录结构并正确配置 pyproject.toml 和包安装方式。
为什么不能把所有代码塞进一个 main.py
因为运行时导入会出错、测试无法隔离、依赖难管理、CI/CD 构建失败——最常见的是 ModuleNotFoundError: No module named 'xxx'。Python 的模块搜索路径（sys.path）默认只含当前目录和 site-packages，没有自动识别“项目根目录”的逻辑。你手动改 sys.path 或靠 IDE 注入路径，上线后就崩。
src/ 目录不是可选，是必须
把源码统一放在 src/ 下，能彻底切断“当前工作目录决定导入行为”的耦合。安装包时用 setuptools 的 package_dir={"": "src"} 映射，确保 pip install -e . 后，无论从哪执行脚本，import myproject 都指向 src/myproject/。
示例结构：
myproject/
├── pyproject.toml
├── src/
│ └── myproject/
│ ├── __init__.py
│ ├── core.py
│ └── cli.py
└── tests/
└── test_core.py
关键点：
-
pyproject.toml中必须声明packages = [{include = "myproject", from = "src"}]（或用find配置） - 测试文件不能放在
src/里，否则会被打包进 wheel - 不推荐用
setup.py，它已过时且易绕过src/隔离
配置文件和数据文件放哪？别放 src/ 里
硬编码路径或用 __file__ 往上跳级找配置，会导致单元测试失败、Docker 构建时找不到文件、Windows/macOS 路径分隔符报错。正确做法是：由入口脚本（如 src/myproject/cli.py）接收配置路径参数，或通过环境变量指定，默认值用 pathlib.Path(__file__).parent.parent / "config" 定位到项目根下独立目录。
建议结构：
myproject/ ├── config/ │ ├── dev.yaml │ └── prod.yaml ├── data/ │ └── sample.csv ├── src/ └── tests/
这样部署时可单独挂载 config/，测试时也能用 tmp_path 模拟。
测试和类型检查要覆盖真实导入路径
如果测试直接 import myproject.core 成功，但 python -m pytest tests/ 报错，说明测试没走 src/ 安装路径。必须确保：
- 测试命令在项目根目录执行（不是
tests/子目录） -
pytest.ini或pyproject.toml中设testpaths = ["tests"]，不加python_paths等 hack -
mypy运行时传--package myproject，而非对src/myproject/目录扫描
否则类型检查会漏掉跨模块引用错误，比如 myproject.cli 导入 myproject.core 时用了未标注的返回值。
真正卡住人的从来不是目录怎么画，而是第一次 pip install -e . 后，发现 import 不生效、测试跑不通、CI 里路径全错——这些都源于没把 src/ 当成边界，而把它当成可有可无的装饰。
