Curtis's Blog

🧩 Nuitka 打包避坑记录（Nuitka Packaging Pitfalls）

October 18

起因

最近做了个一键更改网络适配器的程序，然后在将程序打包的过程中我遇到了一些问题，记录下来方便以后参考 项目地址：https://github.com/CurtisYan/NetAdapterTool photo

一、版本问题：虚拟环境中的 Nuitka 未升级

在我第一次使用 Nuitka 打包时，项目运行在虚拟环境（virtual environment）中，而我使用以下命令升级了 Nuitka：

pip install --upgrade nuitka

然而，这条命令实际上只升级了全局环境（global environment）中的 Nuitka，而虚拟环境里的 Nuitka 并没有被升级。 结果就是：第一次打包失败后，我以为升级成功，第二次打包仍然失败。

✅ 经验教训：

  • 如果你在虚拟环境中工作，记得使用该虚拟环境的 pip。 例如：

    path\to\venv\Scripts\pip install --upgrade nuitka

  • 或者在虚拟环境激活后再执行升级命令。

二、UPX 压缩路径引发 PowerShell 调用异常

我想进一步使用 UPX（Ultimate Packer for eXecutables） 来压缩打包体积，于是下载安装了 UPX。 最初根据网上教程，我直接修改了系统环境变量（Environment Variables）中的 PATH 值，将其更改为 UPX 的路径： 例如：

D:\upx\upx.exe

结果出现了严重问题： 我的项目在运行时需要调用 PowerShell（Windows PowerShell），而修改 PATH 后导致 PowerShell 无法被正常调用。

起初我排查了两遍所有项目代码，完全没发现问题。后来才意识到是 系统 PATH 配置被破坏。 我尝试使用多种命令修复无果，最后在 火绒（Huorong）安全软件 → 系统修复 → 一键修复系统 PATH 功能中才彻底恢复正常。

⚠️ 关键提醒：

  • 不要直接修改 PATH 的值！
  • 应该双击进入 PATH，新增 UPX 路径条目，而不是覆盖原值。
  • 这样不会影响 PowerShell 或其他系统命令。

三、我的 Nuitka 打包命令详解

以下是我最终稳定可用的打包命令：

nuitka ^
  --standalone --onefile ^
  --enable-plugin=pyqt5 ^
  --include-qt-plugins=platforms,imageformats,styles ^
  --python-flag=-OO ^
  --nofollow-import-to=PyQt5.QtQml,PyQt5.QtQuick,PyQt5.QtWebEngineWidgets,PyQt5.QtWebKit,PyQt5.QtMultimedia,PyQt5.QtNetwork,PyQt5.QtSql,PyQt5.QtPrintSupport,tkinter,matplotlib,numpy,pandas ^
  --enable-plugin=upx ^
  --upx-binary="D:\upx\upx.exe" ^
  --onefile-no-compression ^
  --windows-uac-admin ^
  --windows-console-mode=disable ^
  --windows-icon-from-ico=img/NA.ico ^
  --include-data-dir=img=img ^
  --product-name="NetAdapterTool" ^
  --file-version=1.0.0 ^
  --product-version=1.0.0 ^
  --output-filename="网络适配器修改器.exe" ^
  gui.py

🔍 参数说明

参数说明
--standalone / --onefile生成独立可执行文件（standalone executable）。
--enable-plugin=pyqt5启用 PyQt5 插件支持。
--include-qt-plugins=platforms,imageformats,styles仅包含平台、图像格式、样式插件，满足 QIcon/QPixmap(jpg/ico)、窗口显示需求。
--python-flag=-OO删除 docstring 和 assert，减小体积但不影响功能。
--nofollow-import-to=...避免将未使用的 PyQt 模块、numpy、pandas 等大依赖错误打包。
--enable-plugin=upx启用 UPX 压缩插件。
--upx-binary="D:\upx\upx.exe"指定 UPX 可执行文件路径。
--onefile-no-compression单文件打包但不额外压缩，启动速度更快。
--windows-uac-admin生成需要管理员权限的可执行文件。
--windows-console-mode=disable关闭命令行窗口。
--windows-icon-from-ico指定程序图标。
--include-data-dir打包资源目录（images、icons 等）。
--product-name / --file-version / --product-version设置程序元信息。
--output-filename自定义生成的 .exe 文件名。

四、总结与感想

  1. 虚拟环境（Virtualenv）问题 是新手最容易忽略的点。 在虚拟环境中安装或升级依赖时，一定要确保执行的是该环境下的 pip。
  2. UPX 环境变量（Environment Variable） 修改不当会导致系统命令失效。 正确做法是添加而非替换 PATH。
  3. Nuitka 参数 虽多，但理解每一项后其实十分强大，可以媲美 PyInstaller，同时体积更小、性能更优。

五、个人感受

我这次用 GPT-5（Thinking 模式） 帮我优化 Nuitka 指令，体验非常好。 它的思考逻辑远超 Claude 4 —— 思维全面、分析深入、参数解释到位。 唯一的小缺点是：速度有点慢，但慢工出细活，这种质量值得等待。

gpt5

#Nuitka