使用 hatch 等现代 Python 项目工具替代手动维护 PYTHONPATH 或修改激活脚本，是开发中推荐的最佳实践——它能自动处理可编辑安装、路径隔离与环境一致性。
使用 `hatch` 等现代 python 项目工具替代手动维护 `pythonpath` 或修改激活脚本，是开发中推荐的最佳实践——它能自动处理可编辑安装、路径隔离与环境一致性。
在基于 pyproject.toml 和 hatchling 构建的 Python 项目中，手动设置 PYTHONPATH（如 export PYTHONPATH=$PWD/src）虽能临时生效，但存在明显缺陷：它破坏虚拟环境的封装性、易被遗忘或误配置、无法跨 shell 会话复现，且与 pip install . 的已安装包产生冲突（正如你所观察到的——.pth 文件路径被追加而非前置，导致已安装模块优先被导入）。
✅ 推荐方案：采用可编辑安装（Editable Install） + 专用项目管理工具
最符合 Python 官方推荐与现代工程实践的方式是：不依赖 PYTHONPATH，而是通过可编辑模式安装你的包。这使得 import my_module 始终指向源码目录（src/），同时保持虚拟环境纯净、可复现。
以你的项目结构为例：
/path/to/work/dir ├── pyproject.toml ├── src/ │ └── my_module/ │ ├── __init__.py │ ├── src1.py │ └── src2.py
只需执行：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
# 使用 hatch 自动创建并管理 venv（无需手动 python -m venv） hatch shell # 或 hatch run python3 -m my_module.src1 args # 在 hatch 环境中，确保 pyproject.toml 中已声明构建后端为 hatchling # 并在 [project] 下包含： # requires-python = ">=3.8" # dependencies = [...]
hatch 默认会在新建环境中执行 pip install -e .（即“editable install”），等价于：
pip install -e .
该命令会在 venv/lib/pythonX.X/site-packages/my_module.egg-link 中写入 src/ 的绝对路径，并将该路径加入 sys.path 最前端，从而确保 python -m my_module.src1 总是加载你正在编辑的源码，而非已打包安装的副本。
? 补充说明：
- ✅ pip install -e . 是 PEP 517/518 兼容的标准做法，hatch、poetry、pip 均原生支持；
- ❌ 不要修改 venv/bin/activate —— 这违反环境隔离原则，且升级 venv 时丢失配置；
- ❌ 避免全局 PYTHONPATH —— 它可能污染其他项目，且无法被 pylint/mypy 等工具一致识别；
- ✅ 若坚持手动操作，务必使用 -e（editable）标志：pip install -e .，而非 pip install .。
? 小贴士：验证是否生效，可在 Python 中检查：
import my_module print(my_module.__file__) # 应输出类似 /path/to/work/dir/src/my_module/__init__.py
综上，“最佳实践”不是配置路径，而是让工具链正确安装你的包——hatch 提供了开箱即用的可编辑环境、依赖隔离与命令封装，是你当前 workflow 的理想升级路径。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
