【离线部署实战】—— 攻克PyInstaller依赖地狱的完整指南

1. 离线部署PyInstaller的挑战与解决方案

在离线环境下部署PyInstaller确实是个让人头疼的问题。我最近在一个国产化平台上折腾这个，花了整整两天时间才搞定所有依赖问题。最让人崩溃的是，明明按照官方文档一步步操作，却总是卡在某个依赖包上。后来才发现，PyInstaller的依赖链就像多米诺骨牌，安装顺序错一个，后面全乱套。

离线环境最大的痛点有两个：一是依赖包下载困难，二是安装顺序有严格要求。在线环境下pip install能自动解决这些问题，但离线时就得手动处理。我试过直接从PyPI下载所有依赖包，结果发现有些包版本不兼容，有些甚至根本找不到。后来摸索出一套可行方案，这里分享给大家。

提示：在开始之前，建议先准备一个U盘或者移动硬盘，用于在不同机器间转移安装包。另外，最好记录下每个步骤的操作结果，方便排查问题。

2. 准备工作与环境搭建

2.1 获取正确的安装包

首先需要收集所有必要的安装包。我建议在有网络的环境下先创建一个干净的虚拟环境：

python -m venv pyinstaller_env source pyinstaller_env/bin/activate # Linux/Mac pyinstaller_env\Scripts\activate # Windows

然后安装PyInstaller并导出依赖：

pip install pyinstaller pip freeze > requirements.txt pip download -d packages -r requirements.txt

这样就能得到所有需要的whl或tar.gz文件。但要注意，这个方法获取的依赖可能不全，还需要手动补充几个关键包：

• pefile
• future
• pywin32 (Windows平台)
• setuptools (特定版本)

2.2 搭建离线环境

在目标机器上，建议使用与源环境相同的Python版本。我遇到过Python3.7和3.8的兼容性问题，特别是有些包对Python小版本号很敏感。安装顺序应该是：

1. 安装Python解释器
2. 安装setuptools和pip
3. 安装其他基础依赖
4. 最后安装PyInstaller

# 示例安装命令 python -m pip install --no-index --find-links=packages setuptools-xx.whl python -m pip install --no-index --find-links=packages pip-xx.whl

3. 分步安装依赖包

3.1 基础依赖安装

按照我的经验，应该按这个顺序安装基础包：

1. setuptools
2. wheel
3. pip (升级到最新版)
4. future
5. pefile
6. pywin32 (仅Windows)
7. 其他杂项依赖

# 实际安装示例 for package in setuptools-58.1.0-py3-none-any.whl wheel-0.37.1-py2.py3-none-any.whl future-0.18.2.tar.gz pefile-2021.9.3.tar.gz pywin32-303-cp37-cp37m-win_amd64.whl do python -m pip install --no-index --find-links=packages $package done

3.2 解决常见安装错误

安装过程中最常见的三个错误：

1. 版本冲突：可以用pip check命令检查。我遇到最多的是setuptools版本问题，解决方案是强制安装特定版本：

python -m pip install --no-index --find-links=packages --force-reinstall setuptools==58.1.0

2. 平台不匹配：特别是pywin32这类包，必须下载对应Python版本和系统架构的whl文件。

3. 依赖缺失：有些包不会明确声明依赖关系。比如altgraph就是PyInstaller的隐藏依赖，需要手动安装。

4. 安装PyInstaller本体

4.1 选择正确的包格式

PyInstaller有tar.gz和whl两种格式。经过多次测试，我发现whl格式在离线环境下更可靠。特别是从Christoph Gohlke的非官方仓库下载的whl包，兼容性更好。

安装命令很简单，但必须在所有依赖就位后才能执行：

python -m pip install --no-index --find-links=packages pyinstaller-4.3-py3-none-any.whl

4.2 验证安装结果

安装完成后，需要做三个验证：

1. 检查可执行文件位置：

where pyinstaller # Windows which pyinstaller # Linux/Mac

2. 测试基本功能：

pyinstaller --version

3. 尝试打包一个简单脚本：

# hello.py print("Hello, PyInstaller!")

然后运行：

pyinstaller --onefile hello.py

5. 国产化平台适配技巧

在国产化CPU和操作系统上部署时，遇到最多的问题是glibc版本不兼容。我的解决方案是：

1. 使用较旧的PyInstaller版本（如3.6）
2. 从源码编译依赖库
3. 使用conda替代pip管理包

例如，在飞腾CPU上成功部署的步骤：

# 从源码编译安装 tar xzf PyInstaller-3.6.tar.gz cd PyInstaller-3.6 python setup.py install # 验证架构兼容性 file $(which pyinstaller)

6. 故障排查指南

当遇到问题时，可以按照这个流程排查：

1. 检查Python版本匹配性
2. 确认所有依赖包已安装
3. 查看pip安装日志（通常有详细错误信息）
4. 尝试手动安装报错的包
5. 检查环境变量和PATH设置

一个典型的依赖问题解决过程：

# 查看已安装包 pip list # 检查依赖冲突 pip check # 卸载冲突包 pip uninstall conflicting-package # 重新安装指定版本 pip install --no-index --find-links=packages package==1.2.3

7. 最佳实践与经验分享

经过多次离线部署，我总结出几个实用技巧：

1. 保持环境一致：使用Docker或conda创建与生产环境一致的开发环境。

2. 版本冻结：精确记录每个包的版本号，可以用：

pip freeze > requirements.txt

3. 批量安装脚本：编写自动化安装脚本，例如install.sh：

#!/bin/bash for pkg in $(cat requirements.txt) do pip install --no-index --find-links=packages $pkg || echo "Failed to install $pkg" done

4. 备用源准备：除了PyPI，还可以从这些地方获取包：

• Christoph Gohlke的Windows预编译包
• 各Linux发行版的软件源
• Anaconda仓库

最后提醒一点，PyInstaller在打包时会自动分析依赖，但在离线环境下可能会漏掉一些隐式依赖。建议在打包前先用pip check全面检查依赖关系。