PYTHONPATH 不是解决本地模块导入失败的首选方法，因其在导入优先级中位置靠后、易被当前目录覆盖，且在虚拟环境、IDE等场景下不可靠；根本原因在于Python导入机制优先使用sys.path[0]（脚本所在目录）而非PYTHONPATH路径，且要求包结构合规（如含__init__.py）。
PYTHONPATH 不是解决本地模块导入失败的首选方法，它容易掩盖路径设计问题，且在虚拟环境、IDE 或多项目场景下行为不可靠。
为什么 PYTHONPATH 常常不起作用
很多人设了 PYTHONPATH 后仍报 ModuleNotFoundError，根本原因是 Python 导入机制优先级高于环境变量：当前目录（.）和 sys.path[0] 永远排最前；而 PYTHONPATH 对应的路径只是追加到 sys.path 中间偏后的位置。一旦项目结构不满足“包可导入”前提（比如缺少 __init__.py、顶层目录没被识别为包），环境变量也无能为力。
- 运行
python script.py时，sys.path[0]是script.py所在目录，不是你期望的父包目录 - 在子目录里执行
python -m mypackage.module才会把当前目录加入sys.path，这时PYTHONPATH才可能生效 - VS Code、PyCharm 等 IDE 默认不读取 shell 的
PYTHONPATH，需额外配置运行环境
比设置 PYTHONPATH 更可靠的做法
真正解决问题要从 Python 的模块发现逻辑入手，而不是绕开它强行注入路径。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 确保你的模块目录包含
__init__.py（哪怕为空），否则 Python 不认为它是包 - 用
python -m运行：例如项目结构为myproj/→myproj/__init__.py→myproj/utils.py，应在myproj/的父目录下执行python -m myproj.utils - 安装为可编辑包：
pip install -e ./myproj（myproj下必须有setup.py或pyproject.toml），这样模块就永久注册进site-packages路径 - 临时修改
sys.path（仅限调试）：import sys<br>sys.path.insert(0, '/absolute/path/to/myproj')
，但上线前必须移除
PYTHONPATH 的正确设置方式（仅当真需要）
如果因 CI/CD 或遗留脚本约束必须用 PYTHONPATH，务必用绝对路径，并验证是否生效：
立即学习“Python免费学习笔记（深入）”；
- Linux/macOS：在 shell 中运行
export PYTHONPATH="/abs/path/to/myproj:$PYTHONPATH"，然后用python -c "import sys; print(sys.path)"确认路径已出现在输出中 - Windows：用
set PYTHONPATH=C:\abs\path\to\myproj;%PYTHONPATH%（CMD）或$env:PYTHONPATH="C:\abs\path\to\myproj;$env:PYTHONPATH"（PowerShell） - 注意：Python 不会自动递归扫描
PYTHONPATH下的子目录，只认该路径下的直接子目录是否为合法包 - 避免相对路径——
PYTHONPATH=../lib在不同工作目录下行为完全不同
真正难的不是让 Python 找到模块，而是让所有执行上下文（命令行、IDE、测试工具、打包工具）对“哪里是根”有一致理解。硬塞 PYTHONPATH 往往意味着项目结构本身没对齐 Python 的导入契约。
