Files
SikoraDaqReader/PyApp/BUILD.md
T
2026-08-16 12:26:29 +08:00

7.7 KiB
Raw Blame History

SikoraDaqReader 上位机 exe 打包说明

本文档记录将 PyApp/main.py 打包为单文件 exe 的完整步骤、体积优化策略与注意事项。


1. 环境与依赖

1.1 Python 环境

  • Python 3.11(64 位)
  • 依赖包(见 requirements.txt):
    PyQt5>=5.15
    pyqtgraph>=0.12
    pyserial>=3.5
    
  • 打包工具:pyinstaller>=6.0(已随环境安装)

安装依赖:

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
  • 作用:压缩 exe 内嵌的 DLL / PYD,显著减小体积
  • 若缺失,可重新下载:
    $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 中忽略,不会提交到仓库。


3. 打包步骤

3.1 一键打包命令

在项目根目录 D:\Git\SikoraDaqReader 下执行:

# 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 验证启动

$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,采用以下手段将体积从默认 ~80 MB 压缩到 27.6 MB:

4.1 onefile 单文件

EXE 内嵌所有 binaries/datas,分发只需一个文件。

4.2 excludes 排除未使用的第三方库与 PyQt5 子模块

见 main.spec 第 17-41 行。仅排除:

  • 大型第三方库: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 中手动过滤:

类别 处理
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 把缓存重定向到项目内:

$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 中将 upx=True 改为 upx=False(体积会增大到约 45 MB)。

5.5 修改源码后重新打包

修改 main.py 后,重复执行第 3.1 节命令即可。PyInstaller 会增量打包,通常比首次快。若修改了 main.spec 的 excludes,建议先清理 PyApp\build 和 PyApp\dist。


6. 快速参考(复制即用)

# 在项目根目录 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)