python多环境部署五大典型问题：一、虚拟环境未隔离致版本污染；二、.env加载时机或路径错误；三、requirements.txt未锁定子依赖；四、路径硬编码导致迁移失败；五、gunicorn/uvicorn参数未按环境区分。
在 Python 项目部署过程中，当涉及多个运行环境（如开发、测试、预发布、生产）时，常因配置隔离不严、依赖版本冲突或路径误判等问题导致服务异常。以下是实际部署中高频出现的典型问题及对应排查要点：
一、虚拟环境未隔离导致包版本污染
不同环境共用同一 virtualenv 或未激活对应环境，会使 pip install 覆盖全局或交叉环境的包版本，引发运行时 ImportError 或行为不一致。
1、确认当前 shell 中是否已激活目标环境：执行 which python，输出路径应包含 env 名称（如 /path/to/venv-prod/bin/python）。
2、检查已安装包列表是否与预期一致：在对应环境内运行 pip list --outdated，比对 requirements.txt 中声明的版本。
立即学习“Python免费学习笔记（深入）”；
3、禁止使用 sudo pip install：避免包被写入系统 site-packages，应始终在激活环境下执行 pip install -r requirements.txt。
二、.env 文件加载顺序错误或未加载
Python 应用常依赖 python-decouple、dotenv 等库读取 .env 文件，但若加载时机过晚（如在 Django settings.py 导入后才加载），则环境变量无法生效。
1、确保 dotenv.load_dotenv() 在任何依赖环境变量的模块导入前执行，例如在 manage.py 或 app/__init__.py 顶部调用。
2、验证文件路径：默认只加载当前工作目录下的 .env，若启动路径非项目根目录，需显式传入路径参数：load_dotenv('.env.production')。
3、检查文件权限与编码：.env 文件不可含 BOM 头，且需为 UTF-8 编码，否则 load_dotenv 可能静默失败。
三、requirements.txt 生成未锁定子依赖
直接使用 pip freeze > requirements.txt 会导出所有已安装包（含间接依赖），导致跨环境部署时因子依赖版本浮动而出现兼容性问题。
1、改用 pip-compile（来自 pip-tools）生成精确依赖树：先编写 requirements.in，再执行 pip-compile requirements.in 输出带哈希值的 requirements.txt。
2、禁止在生产环境执行 pip install 时不加 --no-deps 或 --force-reinstall 参数，防止意外升级已有依赖。
3、验证依赖一致性：部署后运行 pip check，确认无版本冲突警告。
四、路径硬编码导致跨环境迁移失败
代码中使用绝对路径（如 /home/user/app/config.yaml）或基于 __file__ 的相对路径，在容器化或不同用户部署时会因路径结构差异而报 FileNotFoundError。
1、统一使用 pathlib.Path(__file__).parent.parent.resolve() 构建基准路径，避免 os.path.join 拼接错误。
2、将配置文件路径设为环境变量（如 CONFIG_PATH），启动时通过 os.getenv('CONFIG_PATH', 'config/default.yaml') 动态获取。
3、Docker 部署时，确保 COPY 指令目标路径与代码中预期路径完全一致，例如 COPY ./conf /app/conf。
五、Gunicorn/Uvicorn 启动参数未按环境区分
开发环境常用 reload=True 和 workers=1，但生产环境若遗漏 --workers、--bind 或 --preload 参数，会导致进程模型错配、端口绑定失败或内存泄漏。
1、为各环境定义独立启动脚本，如 gunicorn-prod.conf.py，其中明确设置 workers = multiprocessing.cpu_count() * 2 + 1。
2、禁止在生产环境使用 --reload 参数，该参数仅适用于开发调试，启用后将导致子进程反复 fork。
3、检查 bind 地址：开发常用 127.0.0.1:8000，生产必须设为 0.0.0.0:8000 并配合反向代理，否则外部请求无法到达。
