上位机开发日记 · 第 11 篇 · 打包与发布PyInstaller 与 Nuitka阅读时长约 5 分钟 ·难度进阶 ·前置知识第 10 篇日志与配置代码写完了本篇让它能装到别人电脑上跑。1. 交付前一天的经典场景代码全部完成功能测试通过。你信心满满地把main.py发给现场同事附了一句先装个 Python再pip install -r requirements.txt。第二天收到回复“装 Python 说要装 Visual C 运行库装不上。”“pip 装 pyserial 报错了。”“装好了但双击没反应黑框闪一下就没了。”“我们这边电脑不能联网装东西。”【判断】只要交付对象不是你自己就必须打包。装个 Python 就行在实验室说得通在现场永远说不通——这是上位机交付中最常见也最不必要的一次返工。2. 两种主流方案维度PyInstallerNuitka原理打包字节码 附带 Python 解释器把 Python 编译成 C再编译为机器码产物大小较大较小启动速度稍慢需解包/加载较快逆向难度低字节码可反编译高构建时间快慢首次尤其明显生态成熟度很成熟遇到问题好搜较成熟边界情况稍多适用场景常规交付、内部工具性能敏感、需保护代码命令示意# PyInstallerpyinstaller--noconfirm--windowed--nameTool main.py# Nuitkapython-mnuitka--standalone--enable-pluginpyside6 main.py【判断】默认用PyInstaller快、稳、资料多当有明确的启动速度或代码保护需求时再考虑 Nuitka。不要为了看起来更高级而选 Nuitka—— 它的构建时间和排错成本都是真实代价。顺带一提Nuitka 编译同样能提升纯 Python 计算热点的执行效率如果你的项目里正好有性能瓶颈这一项可以合并考虑。3. 四个必踩的坑坑一资源文件找不到症状源码里跑得好好的打包后启动就报FileNotFoundError。原因打包后程序运行时的目录结构完全变了。源码里那种open(assets/icon.png)的相对路径指向的位置已经不是你以为的地方。解决写一个统一的资源定位函数。importsysfrompathlibimportPathdefresource_path(relative:str)-Path:兼容源码运行、PyInstaller 打包、Nuitka 打包三种情况。ifhasattr(sys,_MEIPASS):# PyInstaller临时解包目录basePath(sys._MEIPASS)elif__compiled__inglobals():# Nuitka编译后的模块目录basePath(__file__).resolve().parentelse:# 源码运行basePath(__file__).resolve().parentreturnbase/relative# 用法iconresource_path(assets/icon.png)【事实】sys._MEIPASS是 PyInstaller 在运行时注入的属性指向解包目录Nuitka 则会定义__compiled__全局变量。两个标记都是各自工具的官方机制。坑二动态导入的模块没被打进去症状报ModuleNotFoundError但那个模块你明明装了、也import了。原因打包工具靠静态分析找依赖。通过字符串导入的模块importlib.import_module(xxx)、插件式加载、部分库的后端选择逻辑它看不到。解决显式声明。pyinstaller --hidden-importpyserial.tools.list_ports main.pyNuitka 用--include-module模块名。排查思路报错里说缺哪个模块就把它加进去如果它还是一个库内部动态加载的去该库的文档里搜packaging或frozen关键字通常有官方说明。坑三驱动与运行库依赖类型问题串口Windows 上可能需要附带 USB 转串口驱动CH340 / FTDI / CP210xVISApyvisa 需要后端NI-VISA / Keysight IO Libraries这部分无法打包要单独安装并写进交付说明VC 运行库部分扩展模块依赖 MSVC 运行库【判断】把需要用户预先安装的东西写成一份交付前置清单比事后解释便宜得多。清单里至少包括驱动、运行库、系统版本、权限要求。坑四首次运行被安全软件拦下平台处理方式macOS未签名应用会被 Gatekeeper 拦住。需要codesign签名分发到外部还需notarytool公证Windows未签名 exe 常被 SmartScreen 或杀软报毒需代码签名证书【判断】如果交付对象是公司内部通常可以走手动允许来绕过但如果对外交付签名与公证必须提前规划——它需要证书申请流程往往要等好几天绝不是交付前一天能搞定的事。4. 打包时机中期就要开始这是本篇最重要的一条建议不要等交付前才第一次打包。理由早期打包能提前暴露的问题为什么拖到后期代价大某个依赖打不进去可能牵动架构要换成可打包的替代库配置文件路径假设错误影响所有文件读写代码需要附带驱动或运行库影响交付文档与用户培训性能和启动速度不达标可能需要换方案重写【判断】建议从项目进行到一半时就固定每两周打一次包并在一台干净的目标机器上跑一遍全流程。把它当成一次小型的集成测试而不是收尾工作。对调试打包版本也有一个小技巧打包时先保留控制台PyInstaller 去掉--windowed这样启动失败时的报错能看到确认稳定后再改成无控制台版本发布。5. 本篇小结记住这一条说明只要交付对象不是你就必须打包别指望现场装 Python默认选 PyInstaller快、稳、资料多有明确需求再上 Nuitka资源路径统一走resource_path()三种运行方式一套代码动态导入要显式声明hidden-import/include-module驱动和运行库写进交付清单VISA 这类后端无法打包签名公证要提前规划流程耗时不能赶中期就开始打包打包是集成测试不是收尾工作打包版先用带控制台的版本调试报错才看得见6. 动手练习今天就打一次包哪怕项目还没完成现在打个包拿到另一台电脑上跑一遍。你大概率会立刻遇到至少一个坑——这比读十篇教程都值。写交付前置清单列出用户需要预先准备什么驱动、运行库、系统版本、目录权限。这份清单会成为你的交付文档的第一页。检查硬编码路径回顾第 10 篇的练习把open()里的字面路径全部改成resource_path()或从配置读取。上一篇[第 10 篇 · 工程化日志与配置]下一篇[第 12 篇 · 测试设备模拟器是核心资产]——能装上了接下来要有办法证明它是对的。