PYTHONPATH 不该设成“全局”，而应按项目粒度配置；强行设成系统级环境变量，会引发跨项目导入冲突、调试混乱和 CI/CD 失败，因其在解释器启动时注入 sys.path 且被所有子进程继承，导致模块查找优先级错乱、路径不存在时静默失效，并与虚拟环境隔离原则相悖。
直接说结论：PYTHONPATH 不该设成“全局”，而应按项目粒度配置；强行设成系统级环境变量，反而会引发跨项目导入冲突、调试混乱和 CI/CD 失败。
为什么 PYTHONPATH 不适合设为系统级全局变量
PYTHONPATH 的作用是向 sys.path 注入路径，它在 Python 解释器启动时读取，且**所有子进程都会继承**。一旦你在系统环境变量里写死一个路径（比如 C:\my_project 或 /home/user/common_libs），后果包括：
- 所有 Python 脚本（包括 pip、pytest、venv 创建脚本）都会优先从这个路径找模块，可能意外覆盖标准库或第三方包
- 多个后端服务共存时，A 项目的
utils会干扰 B 项目的同名utils - Docker 构建或 GitHub Actions 中因环境变量未同步导致
ModuleNotFoundError难以复现
正确做法：按项目启动时动态注入 PYTHONPATH
把 PYTHONPATH 当作“运行时上下文”，而不是“系统配置”。推荐以下三种实操方式，按优先级排序：
-
开发阶段（VS Code / PyCharm）：在
.vscode/settings.json或运行配置中设置env，例如："env": {"PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}/tests"}—— 这样只影响当前调试会话，不污染终端 -
命令行临时运行：在项目根目录下执行：
PYTHONPATH=$(pwd)/src python app.py
（Linux/macOS）或set PYTHONPATH=%cd%\src && python app.py
（Windows CMD）—— 路径基于当前目录，可读性强，无残留 -
生产部署（如 systemd / Docker）：在 service 文件或
Dockerfile中显式声明，例如：Environment="PYTHONPATH=/app/src:/app/shared"
或ENV PYTHONPATH=/app/src—— 与应用生命周期绑定，隔离性好
常见错误：把 PYTHONPATH 和 PATH 混为一谈
很多人误以为 PYTHONPATH 是让 python 命令可用的变量，其实不是：
-
PATH决定操作系统能否找到python可执行文件（即解释器本身） -
PYTHONPATH决定python启动后，import语句去哪找.py文件 - 把项目路径加进
PATH（比如export PATH=$PATH:/my/project）完全无效，Python 不会从PATH里找模块
最易被忽略的细节：PYTHONPATH 里的路径必须存在且可读
Python 启动时会逐个检查 PYTHONPATH 中的每个路径是否真实存在、是否有读权限。只要其中任意一个路径不存在或不可读，整个 PYTHONPATH 就会被静默忽略（不会报错，但也不生效）。验证方法很简单：
python -c "import sys; print([p for p in sys.path if 'your_path' in p])"
如果输出空列表，先检查路径拼写、软链接是否断裂、是否用了相对路径但工作目录已变——这些比语法错误更难定位。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
