使用PyInstaller将PyQt单片机调试工具打包为exe

使用 PyQt 开发的单片机调试上位机通常集成了串口通信（pyserial）、波形可视化（pyqtgraph）以及自定义协议解析等功能。将这类工具分发给没有 Python 环境的产线工人或测试工程师时，需要将其编译为独立的 Windows 可执行文件（.exe）。解决这一需求的核心路径在于：先在隔离的虚拟环境中锁定最小依赖，再对代码中的静态资源寻址进行 sys._MEIPASS 规范化改造，最后通过定制 .spec 规范文件补齐隐式导入与 Qt 平台插件，确保打包后的程序能够脱离 Python 环境稳定运行并正确枚举物理串口。

一、准备工作：创建隔离的纯净虚拟环境

许多开发者在打包上位机时遇到的首个问题是可执行文件体积过大（动辄 300MB 以上）或启动时提示缺少无关依赖。这通常是因为在全局 Python 环境中执行了打包命令，导致 PyInstaller 自动扫描并捆绑了系统中安装的 Pandas、Torch 或 Jupyter 等大型科学计算库。

单片机调试工具应建立专用的虚拟环境，仅安装实现当前上位机功能所必需的包。以下为在 Windows 命令提示符（CMD）或 PowerShell 中的操作步骤：

# 1. 在项目根目录下创建独立虚拟环境
python -m venv venv

# 2. 激活虚拟环境
# Windows CMD 环境下执行：
venv\Scripts\activate.bat
# Windows PowerShell 环境下执行：
venv\Scripts\Activate.ps1

# 3. 升级 pip 并仅安装项目所需的核心依赖
python -m pip install --upgrade pip
pip install PyQt5 pyserial pyqtgraph pyinstaller

安装完成后，建议执行 pip list 检查当前环境中的依赖列表，确认没有多余的第三方扩展包：

规范的单片机上位机工程通常具备如下目录结构，方便后续在打包配置中归类静态资源与运行代码：

mcu_debugger_project/
├── venv/                   # 独立虚拟环境
├── assets/                 # 静态资源（只读）
│   ├── logo.ico            # 窗口与任务栏图标
│   └── serial_status.png   # 串口状态指示图
├── configs/                # 默认协议配置
│   └── modbus_map.json     # 寄存器点位映射表
├── core/                   # 业务逻辑
│   ├── __init__.py
│   ├── serial_worker.py    # 串口收发线程（QThread）
│   └── protocol.py         # 单片机帧格式解析
├── ui/                     # 界面文件
│   └── main_window.ui      # Qt Designer 绘制的界面
├── main.py                 # 程序入口文件
└── main.spec               # 后续生成的打包规范文件

二、关键改造：规范化运行时静态资源寻址

单片机调试工具往往需要加载窗口图标、通道波形配置文件或离线协议描述。如果在 Python 代码中直接使用相对路径（如 open("assets/logo.ico")），打包为单个 exe 运行后程序会立即抛出 FileNotFoundError 异常并崩溃退出。

产生这一现象的原因在于 PyInstaller 的运行机制：在执行单文件（-F）打包的程序时，引导程序会在 Windows 系统的临时目录 %TEMP% 下创建一个以 _MEI 开头的临时工作目录（例如 C:\Users\Username\AppData\Local\Temp\_MEI123456），并将所有捆绑的二进制库与静态资源解压至该目录下。此时，程序运行时的实际资源路径存储在 sys._MEIPASS 变量中，而本地的相对路径则指向了当前执行命令时的目录。

为了使代码在源码开发阶段与打包后均能准确定位资源，需要在项目中编写统一的路径获取函数。在 main.py 或公共工具模块中加入如下代码：

import sys
import os

def resource_path(relative_path: str) -> str:
    """
    获取静态资源的绝对路径。
    开发环境下返回当前脚本相对路径，打包后返回 sys._MEIPASS 临时解压路径。
    """
    if hasattr(sys, '_MEIPASS'):
        # PyInstaller 运行时的临时解压目录
        base_path = sys._MEIPASS
    else:
        # 普通 Python 脚本运行时的项目根目录
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

在 PyQt 界面与业务代码中，所有只读文件加载均调用该函数包装：

from PyQt5.QtGui import QIcon
from PyQt5.QtWidgets import QApplication

# 正确示例：加载上位机窗口图标
icon_path = resource_path("assets/logo.ico")
app.setWindowIcon(QIcon(icon_path))

# 正确示例：加载单片机默认通信协议文件
with open(resource_path("configs/modbus_map.json"), "r", encoding="utf-8") as f:
    protocol_config = f.read()

三、打包模式评估：单文件 (-F) 与单目录 (-D)

PyInstaller 提供了两种核心输出组织形式：单文件模式（-F / --onefile）和单目录模式（-D / --onedir）。根据单片机调试工具的实际应用环境，二者的取舍直接影响软件的响应效率与维护成本。

在工程实践中，推荐在前期联调与排查阶段优先使用 -D 单目录模式；若确实需要单文件交付，也可在 -D 验证无误后，再将成果压缩为 zip 或使用 Inno Setup 打包为安装包分发。

四、编写与定制 .spec 规范文件

虽然可以在命令行直接通过 pyinstaller -F -w main.py 触发打包，但在涉及串口硬件交互、复杂界面和资源绑定的单片机上位机工程中，使用 .spec 规范文件能够更精确地控制动态库抓取、隐式引用及静态数据包含，并支持团队版本控制。

1. 生成初始 Spec 文件

在虚拟环境激活状态下，进入项目根目录，运行 pyi-makespec 命令生成初始模板：

# 生成单目录模式、带图标的初始 spec 文件
pyi-makespec -D --icon=assets/logo.ico main.py

2. 修改并完善 Spec 核心配置

打开生成的 main.spec 文件。由于 pyserial 内部通过动态导入机制探测不同操作系统的底层通信后端，静态分析器往往无法在代码 AST 树中自动发现 serial.tools.list_ports 等模块，必须在 hiddenimports 中显式声明；同时将 assets 和 configs 加入 datas 映射。修改后的完整示例如下：

# -*- mode: python ; coding: utf-8 -*-
import os
import sys

block_cipher = None

# 1. 静态数据资源映射：(源文件路径, 打包后存放的相对目录)
added_datas = [
    ('assets/logo.ico', 'assets'),
    ('assets/serial_status.png', 'assets'),
    ('configs/modbus_map.json', 'configs'),
]

# 2. 隐式依赖导入补全
# 单片机调试工具常在运行时反射加载串口枚举与波形组件
hidden_imports = [
    'serial',
    'serial.tools',
    'serial.tools.list_ports',
    'serial.tools.list_ports_windows',
    'serial.win32',
    'pyqtgraph',
    'PyQt5.QtCore',
    'PyQt5.QtGui',
    'PyQt5.QtWidgets',
]

a = Analysis(
    ['main.py'],
    pathex=['.'],
    binaries=[],
    datas=added_datas,
    hiddenimports=hidden_imports,
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=['matplotlib', 'pandas', 'scipy', 'tkinter', 'notebook'],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,
    name='MCUDebugger',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=True,       # 【关键】调试阶段保留控制台以便查看串口异常日志
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='assets/logo.ico',
)

coll = COLLECT(
    exe,
    a.binaries,
    a.zipfiles,
    a.datas,
    strip=False,
    upx=True,
    upx_exclude=[],
    name='MCUDebugger',
)

3. 执行打包命令

使用修改后的 spec 文件启动编译：

# 使用 --clean 参数清理上一次打包的缓存
pyinstaller --clean main.spec

构建成功后，在 dist/MCUDebugger 目录下即可看到生成的可执行文件及所有依赖项：

五、结果验证与高频报错排查

打包成功并不意味着可以直接发布。必须将生成的 dist/MCUDebugger 目录复制到一台未安装 Python 环境、未安装 VS Code 的纯净 Windows 计算机上进行完整功能回归测试。

1. 异常：程序双击闪退且无任何提示

原因排查：如果在早期构建中指定了 console=False，一旦 Python 脚本在启动初期抛出未捕获异常（如模块导入失败、文件读取错误），操作系统会直接终结进程而不显示任何窗口。

解决方法：在 Windows CMD 中切换至 exe 所在路径，直接输入程序名并回车运行：

cd dist\MCUDebugger
MCUDebugger.exe

此时 CMD 窗口会保留退出前的 Traceback 报错信息，直接指明出错的代码行号与缺失依赖。

2. 异常：报错 "Could not find the Qt platform plugin 'windows'"

这是 PyQt 应用程序打包后最常见的系统级报错，表明 Qt 无法加载窗口系统的平台插件 qwindows.dll。

排查与修复步骤：

1. 检查 dist/MCUDebugger/PyQt5/Qt5/plugins/platforms/（或 dist/MCUDebugger/platforms/）目录下是否存在 qwindows.dll；
2. 如果目录缺失，需在 main.spec 的 datas 字段中手动补全该目录的映射：

   # 补充 PyQt 平台插件
   platforms_path = os.path.join(sys.prefix, 'Lib', 'site-packages', 'PyQt5', 'Qt5', 'plugins', 'platforms')
   added_datas.append((platforms_path, 'PyQt5/Qt5/plugins/platforms'))

3. 若文件存在但依然报错，多为目标主机缺少 Microsoft Visual C++ 运行库（如 VCRUNTIME140.dll），在目标机上安装微软官方 Visual C++ Redistributable (x64/x86) 即可修复。

3. 异常：单片机串口列表无法枚举或报 No module named 'serial.tools'

在开发机上运行正常，但在打包后点击“刷新串口”按钮时，下拉菜单为空或终端提示模块未找到。

原因：pyserial 中的 serial.tools.list_ports 依赖动态平台检测。静态分析时 PyInstaller 漏掉了 serial.tools.list_ports_windows。

修复：检查 main.spec 中的 hiddenimports，务必包含 'serial.tools.list_ports' 和 'serial.tools.list_ports_windows'，保存后重新执行打包。

4. 硬件联调与物理串口测试清单

当上位机窗口成功显示后，需按照以下检查单与单片机硬件进行联调确认：

• 热插拔识别测试：在上位机开启状态下，拔出再重新插入 USB 转串口模块（如 CH340 / CP2102 / FT232），点击刷新确认端口能够重新被识别且不造成界面挂起；
• 高波特率通讯压测：将串口波特率配置为 115200、921600 或更高，由单片机持续向上位机发送高速波形数据包，观察上位机运行 30 分钟以上，确认内存占用平稳、无数据丢失与曲线卡顿；
• 异常断开恢复：在数据收发中途强制拔掉 USB 线，确认后台 QThread 能够捕获 SerialException 优雅退出，而不至于导致上位机进程异常崩溃。

六、总结与发布建议

使用 PyInstaller 打包 PyQt 单片机调试工具的本质是“环境隔离、路径适配与依赖显式声明”三者的结合。只要遵循在干净虚拟环境中编译、使用 sys._MEIPASS 规范化资源寻址、利用 .spec 显式指定 pyserial 隐藏导入与平台插件，并在早期保留控制台进行排查，就能高效输出稳定、可靠的 Windows 独立上位机软件，满足工业调试与产线测试的严苛要求。