Python site模块配置全局第三方库搜索路径

先给出核心结论：site.addsitedir() 仅对当前 Python 进程生效，一旦解释器重启，配置即消失。它不会修改任何配置文件，也不影响 pip 的安装位置——许多初学者误以为调用一次就能“一劳永逸”，结果在脚本中反复写入，甚至指望它让其他进程共享路径，这些想法都是不切实际的。

site.addsitedir() 能否永久修改 sys.path？

答案是否定的。site.addsitedir() 的修改仅作用于当前 Python 进程，它会将指定目录添加到 sys.path 并执行目录内的 .pth 文件，但解释器重启后所有改动都会消失。常见的错误场景包括：在交互式环境中 import mypkg 一切正常，但保存为脚本运行却报 ModuleNotFoundError；或者使用 python -m myscript 启动时路径丢失。根本原因在于，该函数仅影响当前解释器实例，不会写入 site-packages 目录，也不改变 pip 的安装位置。不过，如果目录中包含 .pth 文件，它确实会按规则解析（例如支持 import 语句或 easy-install 风格的路径）。

如何让自定义路径在每次启动 Python 时自动加载？

最可靠的方法并非修改代码或环境变量，而是利用 .pth 文件与默认的 site-packages 目录相结合。Python 启动时会扫描所有已知 site-packages 下的 .pth 文件，并逐行处理——这是官方支持的、可持久化的解决方案。具体操作非常简单：

• 运行 python -c "import site; print(site.getsitepackages())" 查询你的 site-packages 路径（通常为 .../site-packages）
• 在该目录下新建一个文本文件，例如 my_paths.pth
• 文件内容直接写入绝对路径，一行一个，示例如下：

  /home/user/mylibs
      /opt/shared/pyutils

• 确保路径存在且具有读取权限；Python 会自动将其加入 sys.path（无需重启解释器，但新启动的进程才会生效）

需要特别注意的是，.pth 文件不支持相对路径、shell 变量或注释符号；空行和以 # 开头的行会被忽略，但其他任意字符都会导致整行被跳过（不会报错，但路径无效）。

为什么 PYTHONPATH 不总是可靠？

PYTHONPATH 环境变量虽然可以扩展 sys.path，但其效果受 Python 启动方式及 site 模块启用状态的影响。当 Python 以 -s（禁用 site 模块）或 -S（完全跳过 site 初始化）参数运行时，PYTHONPATH 将不会被加载——而许多工具（如某些 IDE 的调试器、pip 内部调用、venv 激活后的子进程）会隐式地添加这些标志。典型问题场景包括：

• 在 PyCharm 中配置了 PYTHONPATH，但 Debug 模式下 import 仍然失败
• pip install --user 安装的包可以导入，但你自己添加的 PYTHONPATH 路径却找不到
• 使用 python -I（隔离模式）时，PYTHONPATH 完全失效

因此，除非你能完全掌控 Python 的启动参数，否则不建议依赖 PYTHONPATH 进行全局路径配置——它非常容易出错。

virtualenv 和 system site-packages 的关系怎么影响路径？

创建虚拟环境时使用 --system-site-packages 参数，将使该环境继承系统 site-packages 中的所有路径（包括你放置的 .pth 文件），但不会继承 PYTHONPATH 或运行时通过 site.addsitedir() 动态添加的路径。关键要点：

• venv 默认禁用系统 site-packages，因此你在系统 site-packages 中放置的 .pth 文件不会生效
• 若使用了 --system-site-packages，则系统级 .pth 文件会被读取，但需注意路径是否在虚拟环境内可达（例如挂载路径、符号链接断裂的情况）
• 不要在 venv 的 site-packages 里手动添加 .pth——它会被视为“该环境专属”，一旦删除 venv 即丢失，且与 pip 产生冲突的风险较高

真正需要跨多个 venv 共享路径时，推荐使用 pip install -e /path/to/pkg，而不是依赖路径注入。

最容易忽略的是 .pth 文件的权限设置和路径实际存在性：Python 不会报错，只是静默跳过不可读或不存在的路径。建议每次修改后，用 python -c "import sys; print('\n'.join(sys.path))" 验证一下是否真的添加进来了。