当使用 zipapp 打包 Python 应用为 .pyz 文件时，即使已内嵌所有依赖，运行仍可能因系统全局 site-packages 中旧版本包（如 zipp 0.6.0）触发 ContextualVersionConflict ——根本原因是默认未启用依赖隔离，需通过虚拟环境强制优先加载内嵌包。
当使用 zipapp 打包 python 应用为 `.pyz` 文件时，即使已内嵌所有依赖，运行仍可能因系统全局 site-packages 中旧版本包（如 zipp 0.6.0）触发 `contextualversionconflict` ——根本原因是默认未启用依赖隔离，需通过虚拟环境强制优先加载内嵌包。
.pyz 文件本质是一个 ZIP 格式的可执行归档，其设计目标是“自包含”（self-contained），但 Python 的导入机制默认仍会搜索 sys.path 中的全局路径（如 /usr/lib/python3.6/site-packages）。当第三方库（例如 importlib-resources）在运行时通过 pkg_resources 或 importlib.metadata 动态解析依赖约束（如 zipp>=3.1.0），而系统中已存在不兼容的旧版 zipp 0.6.0 时，即便 .pyz 内已打包 zipp 3.6.0，Python 仍可能优先匹配全局安装的版本，导致冲突。
关键误区澄清：
- zipapp 本身不自动屏蔽全局 site-packages；
- sys.path 默认顺序为 [
, , ...]，但 pkg_resources 的 WorkingSet 初始化逻辑会扫描全部路径，并按“首次匹配”+“版本约束校验”决定最终加载项； - Gunicorn 等框架常深度依赖 importlib-resources/importlib.metadata，进一步放大该问题。
✅ 可靠解决方案：使用干净的虚拟环境执行 .pyz
虚拟环境通过隔离 sys.path（仅含 venv/lib/pythonX.Y/site-packages 和 venv/bin 相关路径），天然抑制全局包干扰，同时确保 .pyz 中的内嵌模块被优先发现：
# 1. 创建轻量级虚拟环境（无需安装额外包） python3 -m venv .pyz-runtime # 2. 激活环境（Linux/macOS） source .pyz-runtime/bin/activate # Windows 用户请改用：.pyz-runtime\Scripts\activate.bat # 3. 直接运行 pyz（此时 sys.path 已净化） python service.pyz --bind 0.0.0.0:8000 --workers 2 # 4. （可选）退出环境 deactivate
? 为什么有效？
激活虚拟环境后，sys.path[0] 为当前目录（即 .pyz 所在路径），sys.path[1] 为虚拟环境的 site-packages（为空或仅含极简基础包），而系统全局 site-packages 被完全排除在 sys.path 之外。因此 pkg_resources 只能从 .pyz 内部加载 zipp 3.6.0，彻底规避版本冲突。
⚠️ 注意事项与最佳实践：
- 不要在全局 Python 下直接运行 .pyz：即使指定了 -p "/usr/bin/env python3"，也无法绕过全局 site-packages 的污染；
- 避免 pip install 到虚拟环境：本方案依赖“空环境”，若误装了与 .pyz 冲突的包（如旧版 zipp），仍会复现问题；
-
生产部署建议封装为启动脚本：
# start-service.sh #!/bin/bash VENV=".pyz-runtime" if [ ! -d "$VENV" ]; then python3 -m venv "$VENV" fi source "$VENV/bin/activate" exec python service.pyz "$@"
- 替代方案对比：若需更彻底的隔离，可考虑 shiv（专为 .pyz 优化的工具，支持 --no-system-site-packages 标志）或容器化（Docker），但虚拟环境方案零依赖、开销最小、兼容性最佳。
总结：.pyz 的“自包含”是静态打包层面的保证，而非运行时的依赖沙箱。通过虚拟环境激活实现 sys.path 净化，是以最小代价达成真正依赖隔离的标准实践——它不修改打包流程，不增加维护成本，且适用于 Gunicorn、Flask、FastAPI 等所有基于标准 Python 导入机制的 Web 框架。
立即学习“Python免费学习笔记（深入）”；
