一、为什么需要工具分发打包？

在自动化测试与一线运维支撑工作中，我们经常会用 Python + PyQt5 编写一些针对特定业务的分析与排障工具（例如：时序数据比对、日志分析、协议解析器）。

但在将工具分发给业务测试人员或现场运维工程师使用时，常面临巨大阻碍：

• 目标机器没有安装 Python 运行时，或者 Python 大版本不兼容；
• 目标机器缺少 PyQt5、pandas、openpyxl、protobuf 等数十个第三方依赖库；
• 源码直接分发容易引发意外修改或业务配置泄露。

通过 PyInstaller，我们可以将 Python 解释器、所有依赖包以及自建模块整体打包为一个完全独立的单文件可执行程序（Windows 下为 .exe，Linux 下为二进制可执行文件），实现免安装双击即用。

---

二、PyInstaller 常用参数速查表

参数	全称	说明
-F	--onefile	将整个项目及其所有动态链接库打包成单个独立的 .exe
-w	--noconsole	隐藏启动时的黑屏控制台窗口（适合带 GUI 界面的应用）
-i <file.ico>	--icon	为生成的可执行程序指定专属图标
-p <dir_path>	--paths	显式向 PyInstaller 注入自定义模块搜索路径（类似 PYTHONPATH）
--hidden-import	--hidden-import	核心排坑参数：强制打包隐式/动态导入的底层模块
--clean	--clean	在构建前清理临时缓存，防止历史编译脏数据污染

---

三、核心大坑：动态导入模块丢失（--hidden-import）

使用 -F 打包完成后，双击程序闪退或在日志中抛出如下异常：

ModuleNotFoundError: No module named 'google'
# 或者
ModuleNotFoundError: No module named 'openpyxl.cell._writer'

根因剖析：

PyInstaller 在静态分析源码时，只能分析顶层显式书写的 import xxx 语句。如果某个第三方库（如 Protocol Buffers 的 google.protobuf，或者 openpyxl 底层按需动态反射加载的 _writer）是在运行时动态加载的，PyInstaller 的静态扫描树会判定该模块“未被使用”，从而将其从最终的打包镜像中剔除。

✅ 解决方案：显式声明隐藏导入

针对常用库的隐式丢失，通过 --hidden-import 强制打包：

# 解决 Protobuf 动态加载丢失：
pyinstaller -F -w -i app_logo.ico main.py --hidden-import=google.protobuf

# 解决 OpenPyXL 导出 Excel 模块缺失：
pyinstaller -F -w -i app_logo.ico main.py --hidden-import=openpyxl.cell._writer

---

四、大型多模块多文件工程化打包命令

对于包含多个业务模块、自建工具库以及多个界面的完整工程：

pyinstaller -F -w \
  -i resources/logo.ico \
  -p ./src \
  -p ./src/ui \
  -p ./src/service \
  --hidden-import=google.protobuf \
  --hidden-import=openpyxl.cell._writer \
  --hidden-import=psycopg2 \
  --clean \
  main.py

关键工程参数解析：

1. -p ./src -p ./src/ui：确保代码中写 from ui.panel import MainPanel 或 import db_service 时，打包器能正确定位并打包源码文件；
2. 构建产物归档：
   • 临时文件存放在 build/；
   • 最终可分发的独立安装包位于 dist/main.exe；
   • 附带生成的 main.spec 规格文件可被直接提交至 Git 仓库，后续直接运行 pyinstaller main.spec 即可实现确定性的标准化自动化构建。