Python .pyz 可执行文件依赖隔离失效问题的解决方案

当使用 zipapp 打包 Python 应用为 .pyz 文件时，即使已内嵌所有依赖，运行仍可能因系统全局 site-packages 中旧版本包（如 zipp 0.6.0）干扰而触发 ContextualVersionConflict——根本原因是 Python 默认未隔离运行时模块搜索路径。

当使用 `zipapp` 打包 python 应用为 `.pyz` 文件时，即使已内嵌所有依赖，运行仍可能因系统全局 site-packages 中旧版本包（如 `zipp 0.6.0`）干扰而触发 `contextualversionconflict`——根本原因是 python 默认未隔离运行时模块搜索路径。

在构建自包含的 .pyz 可执行文件时，一个常见但易被忽视的关键点是：.pyz 本身并不自动启用依赖隔离。尽管 zipapp 将你的源码和第三方包（如 zipp>=3.1.0）全部打包进 ZIP 归档，并通过 __main__.py 或 -m 指定入口启动，Python 解释器在导入模块时仍会按默认顺序搜索 sys.path ——该路径通常包含系统级 site-packages（例如 /usr/lib/python3.6/site-packages），导致旧版全局包（如 zipp 0.6.0）优先于 .pyz 内嵌版本被加载。这正是你遇到 pkg_resources.ContextualVersionConflict 的根源：importlib-resources 运行时动态检查依赖约束 zipp>=3.1.0，却实际加载了系统中不兼容的 0.6.0。

✅ 正确做法是显式启用运行时环境隔离。最可靠、跨平台且符合 Python 最佳实践的方式是：在干净的虚拟环境中执行 .pyz 文件。虚拟环境通过重置 sys.path 并禁用系统 site-packages（除非显式启用 --system-site-packages），确保所有 import 均优先命中 .pyz 内部的模块。

以下为完整操作流程：

NNiji·Journey

二次元风格绘画生成器，由 Spellbrush 与 Midjourney 共同设计开发

# 1. 创建轻量级虚拟环境（无需安装额外包）
python3 -m venv .pyz-env

# 2. 激活环境（Linux/macOS）
source .pyz-env/bin/activate
# Windows 用户请使用：.pyz-env\Scripts\activate

# 3. 直接运行 .pyz（此时 Python 仅搜索 venv + .pyz，跳过系统 site-packages）
python service.pyz

# ✅ 验证：可检查是否加载了内嵌 zipp
python service.pyz -c "import zipp; print(zipp.__version__)"
# 输出应为 3.6.0（而非 0.6.0）

⚠️ 注意事项：

• 不要在系统 Python 下直接运行 .pyz：即使指定了 -p "/usr/bin/env python3"，该参数仅控制 shebang 解释器，不改变 sys.path 行为；
• 避免 --system-site-packages：创建 venv 时切勿添加此标志，否则会重新引入冲突风险；
• Gunicorn 集成建议：若需在生产脚本中调用，可将上述三步封装为 shell 函数或 systemd service，例如：

  # /etc/systemd/system/my-service.service
  [Service]
  ExecStart=/bin/sh -c 'source /path/to/.pyz-env/bin/activate && exec python /path/to/service.pyz --bind 0.0.0.0:8000'

• 替代方案（高级用户）：若无法使用 venv，可通过 PYTHONNOUSERSITE=1 PYTHONPATH=/dev/null 强制清理路径，但不如 venv 稳定可靠，且可能影响标准库行为。

总结而言，.pyz 是优秀的分发格式，但它并非“沙箱”——它依赖 Python 运行时的环境配置来保障依赖一致性。虚拟环境不是可选项，而是 .pyz 生产部署的必需前置条件。 通过这一简单隔离步骤，即可彻底规避全局包版本污染，让内嵌依赖真正“自包含”。