使用.pth文件可永久生效地添加模块路径，因其被Python官方机制支持且不依赖环境变量，但需确保.pth文件置于site.getsitepackages()返回的目录中、路径正确无误、末尾无斜杠、对应目录含__init__.py，并重启Python进程。
为什么 easy_install 或 pip install --user 没生效？
因为 Python 启动时只扫描固定位置的 site-packages 目录，而用户级安装（如 --user）默认写入的是 ~/.local/lib/python3.x/site-packages（Linux/macOS）或 %APPDATA%\Python\Python3x\site-packages（Windows），这个路径未必在当前 Python 解释器的 sys.path 中——尤其当你用的是虚拟环境、conda 环境、或系统 Python 和 pyenv 切换混用时。
直接修改 sys.path 只对当前进程有效；想让所有脚本（包括 python -m、IDE 自动补全、调试器导入）都识别某个目录，最稳定的方式是往已加载的 site-packages 里丢一个 .pth 文件。
-
.pth文件必须放在某个已被 Python 自动扫描的site-packages目录下（可通过python -c "import site; print(site.getsitepackages())"查看） - 文件内容每行一个绝对路径，空行和以
#开头的行会被忽略 - 路径可以是普通目录，也可以是包含
.pth的 zip 文件（较少用） - 如果路径不存在，Python 会静默跳过，不报错也不警告
如何确认目标 site-packages 目录并创建 .pth 文件
先运行命令定位当前解释器实际使用的 site-packages：
python -c "import site; print('\n'.join(site.getsitepackages()))"
选第一个（通常是主 site-packages），然后进入该目录，新建一个文本文件，比如 myproject.pth：
立即学习“Python免费学习笔记（深入）”；
- Linux/macOS：
echo "/path/to/your/module" > /usr/local/lib/python3.11/site-packages/myproject.pth - Windows（PowerShell）：
"C:\my\custom\module" | Out-File -FilePath "$env:LOCALAPPDATA\Programs\Python\Python311\Lib\site-packages\myproject.pth" -Encoding UTF8 - 注意：路径必须是绝对路径，不能用
~或环境变量（如$HOME） - 文件编码用 UTF-8（无 BOM），否则 Windows 上可能解析失败
为什么加了 .pth 还 import 不到模块？
常见原因不是路径写错，而是 Python 没重新扫描 .pth——它只在启动时读一次。你改完文件后必须重启 Python 进程（包括 Jupyter kernel、IDE 的 Python 控制台、VS Code 的 Python REPL）。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
验证是否生效：
python -c "import sys; print([p for p in sys.path if 'site-packages' in p])"
再检查你的自定义路径是否出现在输出中。如果没出现，说明：
-
.pth文件不在getsitepackages()返回的任一目录里（比如误放进了dist-packages—— Ubuntu/Debian 系统用这个名，但getsitepackages()仍返回正确路径） - 路径拼写错误，或大小写不一致（macOS 默认不区分大小写，但 Python 解析
.pth时按字面匹配） - 路径末尾带斜杠（
/path/to/module/）会导致导入失败，应写成/path/to/module - 该路径下没有
__init__.py（即使是空文件），Python 3.3+ 虽支持 namespace package，但多数工具链仍依赖__init__.py触发包识别
.pth 和 PYTHONPATH 哪个更可靠？
PYTHONPATH 看似简单，但它依赖 shell 环境，容易漏配（比如 systemd service、cron、GUI 应用启动的 Python 进程根本看不到它），而且 IDE、Jupyter、pip 内部调用等场景行为不一致。
.pth 是 Python 官方机制，被所有符合规范的解释器（CPython、PyPy）和几乎所有工具链尊重，只要路径放进正确的 site-packages，就“永久生效”。唯一要注意的是：不同 Python 版本（如 3.9 vs 3.11）、不同环境（venv vs conda）的 site-packages 是隔离的，得分别配置。
真正容易被忽略的点是：conda 环境的 site-packages 通常在 envs/xxx/lib/python3.x/site-packages，而 conda 自己的 pkgs/ 缓存目录不是 site-packages，往那里扔 .pth 没用。
