180 lines
7.7 KiB
Markdown
180 lines
7.7 KiB
Markdown
# SikoraDaqReader 上位机 exe 打包说明
|
||
|
||
本文档记录将 [PyApp/main.py](main.py) 打包为单文件 exe 的完整步骤、体积优化策略与注意事项。
|
||
|
||
---
|
||
|
||
## 1. 环境与依赖
|
||
|
||
### 1.1 Python 环境
|
||
- Python 3.11(64 位)
|
||
- 依赖包(见 [requirements.txt](requirements.txt)):
|
||
```
|
||
PyQt5>=5.15
|
||
pyqtgraph>=0.12
|
||
pyserial>=3.5
|
||
```
|
||
- 打包工具:`pyinstaller>=6.0`(已随环境安装)
|
||
|
||
安装依赖:
|
||
```powershell
|
||
pip install -r PyApp/requirements.txt
|
||
pip install pyinstaller
|
||
```
|
||
|
||
### 1.2 UPX 压缩工具
|
||
- 版本:UPX 4.2.4(win64)
|
||
- 位置:[PyApp/upx/upx-4.2.4-win64/upx.exe](upx/upx-4.2.4-win64/upx.exe)
|
||
- 作用:压缩 exe 内嵌的 DLL / PYD,显著减小体积
|
||
- 若缺失,可重新下载:
|
||
```powershell
|
||
$url = "https://github.com/upx/upx/releases/download/v4.2.4/upx-4.2.4-win64.zip"
|
||
Invoke-WebRequest -Uri $url -OutFile PyApp\upx.zip -UseBasicParsing
|
||
Expand-Archive -Path PyApp\upx.zip -DestinationPath PyApp\upx -Force
|
||
Remove-Item PyApp\upx.zip
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
PyApp/
|
||
├── main.py # 上位机源码
|
||
├── requirements.txt # Python 依赖
|
||
├── main.spec # PyInstaller 打包配置(核心)
|
||
├── upx/ # UPX 压缩工具(已下载, 已 gitignore)
|
||
│ └── upx-4.2.4-win64/upx.exe
|
||
├── pyicache/ # PyInstaller 缓存(已 gitignore)
|
||
├── build/ # 打包中间产物(已 gitignore)
|
||
└── dist/ # 打包输出(已 gitignore)
|
||
└── SikoraDaqReader.exe # 最终单文件 exe
|
||
```
|
||
|
||
打包产物(`build/`、`dist/`、`pyicache/`、`upx/`)已在 [.gitignore](../.gitignore) 中忽略,不会提交到仓库。
|
||
|
||
---
|
||
|
||
## 3. 打包步骤
|
||
|
||
### 3.1 一键打包命令
|
||
|
||
在项目根目录 `D:\Git\SikoraDaqReader` 下执行:
|
||
|
||
```powershell
|
||
# 1) 把 UPX 加入 PATH(供 PyInstaller 调用)
|
||
$env:Path = "D:\Git\SikoraDaqReader\PyApp\upx\upx-4.2.4-win64;$env:Path"
|
||
|
||
# 2) 把 PyInstaller 缓存重定向到项目内(见第 5.1 节说明)
|
||
$env:PYINSTALLER_CONFIG_DIR = "D:\Git\SikoraDaqReader\PyApp\pyicache"
|
||
|
||
# 3) (可选)清理上次产物
|
||
Remove-Item -Recurse -Force PyApp\build, PyApp\dist -ErrorAction SilentlyContinue
|
||
|
||
# 4) 执行打包
|
||
python -m PyInstaller PyApp\main.spec --noconfirm --distpath PyApp\dist --workpath PyApp\build
|
||
```
|
||
|
||
### 3.2 产物
|
||
- 输出文件:`PyApp/dist/SikoraDaqReader.exe`
|
||
- 体积:约 **27.6 MB**(单文件,无外部依赖)
|
||
- 直接双击即可运行
|
||
|
||
### 3.3 验证启动
|
||
```powershell
|
||
$p = Start-Process -FilePath "D:\Git\SikoraDaqReader\PyApp\dist\SikoraDaqReader.exe" -PassThru
|
||
Start-Sleep -Seconds 4
|
||
if ($p.HasExited) { Write-Output "FAILED code=$($p.ExitCode)" }
|
||
else { Write-Output "RUNNING_OK"; $p.Kill() }
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 体积优化策略(main.spec 说明)
|
||
|
||
打包配置在 [main.spec](main.spec),采用以下手段将体积从默认 ~80 MB 压缩到 27.6 MB:
|
||
|
||
### 4.1 onefile 单文件
|
||
EXE 内嵌所有 binaries/datas,分发只需一个文件。
|
||
|
||
### 4.2 excludes 排除未使用的第三方库与 PyQt5 子模块
|
||
见 [main.spec 第 17-41 行](main.spec)。仅排除:
|
||
- **大型第三方库**:scipy / pandas / matplotlib / cv2 / h5py / lxml / sqlalchemy 等(环境中存在但本程序未使用)
|
||
- **PyQt5 子模块**:QtWebEngine / QtQml / QtQuick / QtMultimedia / QtNetwork / QtSvg 等 30+ 个(本程序仅用 QtCore/QtGui/QtWidgets)
|
||
- **第三方工具链**:setuptools / pip / ensurepip / wheel
|
||
|
||
> ⚠️ **绝对不能把 Python 标准库模块(urllib/http/xml/html/email 等)放入 excludes**,详见第 5.2 节。
|
||
|
||
### 4.3 过滤 a.binaries(仅保留必需 Qt5 DLL)
|
||
PyQt5 钩子会无条件收集整个 `Qt5\bin` 目录与全部插件,需在 [main.spec 的 _is_unneeded_binary](main.spec) 中手动过滤:
|
||
|
||
| 类别 | 处理 |
|
||
|------|------|
|
||
| Qt5*.dll | 仅保留 Qt5Core / Qt5Gui / Qt5Widgets,其余(Qt5Qml/Qt5Quick/Qt5Network/Qt5Svg/Qt5DBus...)全删 |
|
||
| OpenGL 相关 | 删除 opengl32sw.dll / d3dcompiler_47.dll / libEGL.dll / libGLESv2.dll(pyqtgraph 用 2D 绘图,不需要 OpenGL) |
|
||
| 平台插件 platforms | 仅保留 qwindows.dll,删除 qminimal/qoffscreen/qwebgl |
|
||
| QML 运行时 | 删除 /qml/ /qtqml/ 目录 |
|
||
| 其他插件 | 删除 mediaservice/audio/sqldrivers/sensors/printsupport/bearer/tls 等未用插件目录 |
|
||
| 图片格式 | 仅保留 gif/ico/jpeg/svg,删除 icns/tga/tiff/wbmp/webp |
|
||
|
||
### 4.4 UPX 压缩
|
||
`upx=True`,所有 DLL/PYD 经 UPX LZMA 压缩。
|
||
|
||
### 4.5 无控制台窗口
|
||
`console=False`(windowed 模式)。
|
||
|
||
### 4.6 优化效果
|
||
| 阶段 | 体积 | 手段 |
|
||
|------|------|------|
|
||
| 默认打包 | ~80 MB | — |
|
||
| + excludes 第三方库 | 40.4 MB | 排除 scipy/pandas/matplotlib/opencv 等 |
|
||
| + 排除 h5py | 35.3 MB | excludes 加 h5py(hdf5.dll 等) |
|
||
| + 过滤 Qt5 DLL/OpenGL/插件 | **27.6 MB** | _is_unneeded_binary 过滤 |
|
||
|
||
---
|
||
|
||
## 5. 常见问题与注意事项
|
||
|
||
### 5.1 `--clean` 报错 / bincache 损坏
|
||
**现象**:使用 `--clean` 时报 `OSError: [WinError 145] 目录不是空的` 或 `FileNotFoundError`,指向 `C:\Users\<user>\AppData\Local\pyinstaller\bincache01py31164bit\...`。
|
||
|
||
**原因**:`--clean` 会清理 AppData 下的 PyInstaller bincache,但该目录可能因权限/沙箱/旧缓存损坏而无法删除。
|
||
|
||
**解决**:**不要用 `--clean`**,改用环境变量 `PYINSTALLER_CONFIG_DIR` 把缓存重定向到项目内:
|
||
```powershell
|
||
$env:PYINSTALLER_CONFIG_DIR = "D:\Git\SikoraDaqReader\PyApp\pyicache"
|
||
```
|
||
这样 bincache 建在项目目录,可自由清理,且避开 AppData 的损坏缓存。修改 spec 的 excludes 后,配置哈希变化,旧缓存不会被复用,无需 `--clean`。
|
||
|
||
> 注意:环境变量名是 `PYINSTALLER_CONFIG_DIR`,不是 `PYINSTALLER_CACHE_DIR`。
|
||
|
||
### 5.2 `ModuleNotFoundError: No module named 'urllib'`
|
||
**现象**:exe 启动即崩溃,堆栈指向 `pyi_rth_inspect.py → pathlib.py → zipfile.py → ModuleNotFoundError: 'urllib'`。
|
||
|
||
**原因**:这是 PyInstaller **启动 runtime hook(rthook)阶段**的错误(应用代码尚未运行)。把标准库模块(urllib/http/xml/html/email 等)放入 `excludes` 会打断标准库内部的依赖链(pathlib/zipfile 间接依赖 urllib)。
|
||
|
||
**解决**:`excludes` **只能放第三方库和 PyQt5 子模块,绝不能放 Python 标准库模块**。若想缩减标准库,必须依赖 PyInstaller 自身的运行期分析,不要手动 exclude 顶层标准库名。
|
||
|
||
### 5.3 移除 OpenGL DLL 后能否正常运行
|
||
可以。pyqtgraph 的 PlotWidget 使用 QPainter(2D)绘图,不依赖 OpenGL。Qt5 在 Windows 上 2D 渲染走 GDI/CPU,无需 opengl32sw/libGLESv2/d3dcompiler。已通过启动验证。
|
||
|
||
### 5.4 杀毒软件误报
|
||
UPX 压缩的 exe 可能被部分杀毒软件误报。若介意,可在 [main.spec](main.spec) 中将 `upx=True` 改为 `upx=False`(体积会增大到约 45 MB)。
|
||
|
||
### 5.5 修改源码后重新打包
|
||
修改 `main.py` 后,重复执行第 3.1 节命令即可。PyInstaller 会增量打包,通常比首次快。若修改了 `main.spec` 的 excludes,建议先清理 `PyApp\build` 和 `PyApp\dist`。
|
||
|
||
---
|
||
|
||
## 6. 快速参考(复制即用)
|
||
|
||
```powershell
|
||
# 在项目根目录 D:\Git\SikoraDaqReader 下执行
|
||
$env:Path = "D:\Git\SikoraDaqReader\PyApp\upx\upx-4.2.4-win64;$env:Path"
|
||
$env:PYINSTALLER_CONFIG_DIR = "D:\Git\SikoraDaqReader\PyApp\pyicache"
|
||
Remove-Item -Recurse -Force PyApp\build, PyApp\dist -ErrorAction SilentlyContinue
|
||
python -m PyInstaller PyApp\main.spec --noconfirm --distpath PyApp\dist --workpath PyApp\build
|
||
```
|
||
|
||
产物:`PyApp\dist\SikoraDaqReader.exe`(约 27.6 MB)
|