Open for new projects · sublimearts.io
← Blog
Windows Dev2026年6月10日·12分钟阅读

使用Nuitka编译Python独立可执行文件 以消除机器开销。

这是在Windows上发布超快.exe文件的权威指南,无需依赖PyInstaller这类缓慢的运行时打包工具。ReelNox Studio和BackDrop_正是这样交付给真实用户的——包括我一路走来犯的每一个错误。

喜欢这篇文章吗?文末有一个❤️在等你。

为什么非得编译Python

如果你用Python开发桌面应用,并希望普通人也能运行它,那么“pip install”就不是一个选项。他们没有安装Python,不想安装,也不该被要求安装。你需要一个可以双击运行的真正的.exe。这意味着要编译——把你的解释型Python代码及其依赖,变成无需在目标机器上安装Python就能运行的东西。

为什么PyInstaller不够好

PyInstaller是我的第一次尝试,它能用——技术上如此。问题在于它实际做了什么:它把Python解释器和你所有的依赖打包在一起,然后在每次应用启动时把它们解压到临时文件夹(--onefile模式),或者以一个装满零散文件的文件夹形式发布(--onedir模式)。无论哪种方式,启动时你运行的仍然是通过内嵌Python运行时解释执行的字节码,而不是编译后的机器码。启动感觉迟钝,临时解压这一步让首次启动出现了明显延迟,而且杀毒软件把“自行解压到%TEMP%并开始执行”视为典型的恶意软件启发式特征——这恰恰引发了我想避免的误报问题。

正确的做法:Nuitka --standalone

Nuitka是真正的Python到C的编译器。它不打包解释器——而是把你的Python代码翻译成C,用真正的C编译器编译,再链接成一个货真价实的原生可执行文件。结果是作为编译后的机器码运行,而不是在内嵌运行时里解释执行字节码。启动几乎是瞬时的,而且关键在于,它在运行时从不把自己解压到临时文件夹,这就消除了杀毒启发式最大的单一触发点。最重要的参数是--standalone:它会生成一个自包含的文件夹,里面是你的.exe以及紧挨着它的原生依赖,可以原样分发,或封装进安装程序。

具体怎么做

1安装Nuitka:pip install nuitka(机器上需要C编译器——Windows上是MSVC;如果你还没有Visual Studio Build Tools,Nuitka安装程序可以帮你获取)
2运行编译:python -m nuitka --standalone --enable-plugin=tk-inter --windows-console-mode=disable --output-dir=dist main.py
3Nuitka会生成dist/main.dist/文件夹,其中包含main.exe以及它检测到的所有原生依赖——你要分发的是整个文件夹,而不仅仅是.exe
4用安装程序封装该文件夹(我用的是Inno Setup),让用户获得正常的Windows安装体验,而不是一个散落文件的文件夹
5发布前,在没有安装Python的干净Windows虚拟机上测试已安装的应用——这是发现缺失DLL或只在你开发机上有效的资源路径的唯一办法

让我折腾了几个小时的3个错误

⚠️ 忘了加--enable-plugin=tk-inter

如果你的界面使用Tkinter或CustomTkinter,却漏掉这个参数,编译后的应用不会大声报错——它只是无法加载GUI工具包,可能悄无声息地崩溃,或者显示一个空白窗口。Nuitka默认不包含GUI框架支持,你必须逐个框架手动启用。

⚠️ 用了--onefile而不是--standalone

--onefile很诱人,因为它生成单个.exe而不是一个文件夹。对任何打算公开分发的东西,都不要用它。Onefile构建在运行时仍会自行解压到临时目录——这正是让PyInstaller触发误报的同一行为——我见过Windows Defender仅仅因为这种解压模式就把它们标记为Wacatac或Sabsik,而代码本身完全干净。--standalone完全避开了这个问题。

⚠️ 用__file__而不是sys.executable解析资源路径

在普通Python脚本中,__file__指向你源文件的位置。在编译后的独立构建中,这个假设不再成立。请使用Path(sys.executable).parent找到.exe在用户机器上的实际位置,并相对于它加载配置文件、图标和打包的资源——而不是相对于开发时源码碰巧所在的位置。

这样做究竟能带来什么

ReelNox Studio和BackDrop_都以Nuitka --standalone构建的形式发布,并使用DigiCert EV证书进行代码签名。启动是瞬间的,Windows Defender不会标记这两个安装程序,也从来不需要用户去操心任何随附的Python运行时。真正关键的组合是:--standalone(而不是--onefile)加上规范的代码签名——两者一起,既解决了性能问题,也解决了把Python应用作为原生Windows可执行文件分发时的信任问题。

看看实际运行 → ReelNox Studio使用Nuitka --standalone构建,GPU加速,EV代码签名

About

Patrick Chen——Sublimearts.io背后的独立开发者。我写的是自己在把ReelNox Studio、BackDrop_和Time Precision交付给真实Windows用户时亲身碰到的构建问题,而不是泛泛的教程。

Did you find this helpful?