====== Nuitka Python 打包指南 ======

Nuitka 是一个 Python 编译器，它是目前 Python 打包成可执行文件（EXE）方案中，**安全性（防反编译）**和**运行效率**最高的工具之一。

尽量不要有中文路径，python版本要合适。

===== 1. 为什么选择 Nuitka？ =====

与 PyInstaller 等传统打包工具相比，Nuitka 有显著区别：

^ 特性 ^ PyInstaller ^ Nuitka ^
| **原理** | 捆绑 Python 解释器和字节码 (.pyc) | 将 Python 翻译成 C++，再编译成机器码 |
| **安全性** | **低**。极易被反编译还原源码 | **极高**。反编译难度等同于逆向 C++ 程序 |
| **性能** | 与原脚本一致，启动稍慢 | 通常比原脚本快，启动速度快 |
| **体积** | 较大 | 相对较小（依赖于具体库） |

===== 2. 环境准备 =====

在开始之前，你需要确保系统中安装了 Python 和 C++ 编译器。

==== 2.1 安装 Nuitka ====

直接使用 pip 安装：

<code bash>
pip install nuitka
</code>

==== 2.2 配置 C++ 编译器 ====

Nuitka 需要 C++ 编译器将翻译后的代码编译成二进制文件。
*   **Windows:** 推荐安装 **MinGW64** 或者 **Visual Studio 2022 (MSVC)**。
    *   //提示：首次运行 Nuitka 时，如果检测不到编译器，它通常会提示你自动下载 MinGW64，按照提示输入 ``yes`` 即可。//
*   **Linux/macOS:** 通常系统自带 GCC 或 Clang，无需额外配置。

===== 3. 常用打包命令 =====

假设你的入口文件是 ''main.py''。

==== 3.1 基础打包（生成文件夹） ====

这是最稳健的模式，生成一个包含 EXE 和依赖文件的文件夹。

<code bash>
nuitka --standalone --show-progress --show-memory main.py
</code>

*   ''--standalone'': 独立环境，使程序可以移植到其他机器运行。
*   ''--show-progress'': 显示编译进度条。

==== 3.2 单文件打包（生成一个 EXE） ====

生成单独的一个 EXE 文件，分发方便，但启动时需要解压，速度稍慢。

<code bash>
nuitka --standalone --onefile main.py
</code>

*   ''--onefile'': 启用单文件模式。

==== 3.3 去除控制台窗口（GUI 程序专用） ====

如果你开发的是 PyQt、Tkinter 等图形界面程序，不希望后台弹出黑色的 CMD 窗口。

<code bash>
nuitka --standalone --onefile --windows-disable-console main.py
</code>

*   ''--windows-disable-console'': 禁用 Windows 控制台。

==== 3.4 添加图标 ====

<code bash>
nuitka --standalone --onefile --windows-icon-from-ico=app_icon.ico main.py
</code>

===== 4. 处理第三方库和数据文件 =====

Nuitka 能够自动识别大多数库，但有时需要手动干预。

==== 4.1 启用特定插件 ====

某些复杂的库（如 NumPy, PyQt, Tkinter）需要启用对应的插件才能正常工作。

<code bash>
# 示例：启用 Tkinter 和 NumPy 插件
nuitka --standalone --enable-plugin=tk-inter --enable-plugin=numpy main.py
</code>

查看所有可用插件：
<code bash>
nuitka --plugin-list
</code>

==== 4.2 包含额外的数据文件 ====

如果你的程序需要读取配置文件、图片等资源。

<code bash>
# 格式：--include-data-dir=源路径=目标路径
nuitka --standalone --include-data-dir=assets=assets main.py

# 或者包含单个文件
nuitka --standalone --include-data-files=config.ini=config.ini main.py
</code>

===== 5. 常见问题 (FAQ) =====

== Q: 编译速度为什么这么慢？ ==
A: Nuitka 需要进行两次编译（Python -> C++ -> Binary），且会对代码进行静态分析和优化。第一次编译通常较慢，后续开启 ''--ccache'' 可以利用缓存加速。

== Q: 缺少 DLL 或 Module 报错怎么办？ ==
A: 
  - 确保使用了对应的插件（如 ''--enable-plugin=pyqt5''）。
  - 使用 ''--follow-imports'' 强制跟随导入。
  - 检查是否是动态加载的库，尝试手动 import 隐藏的模块。

== Q: 防病毒软件报毒？ ==
A: 使用 ''--onefile'' 模式生成的 EXE 偶尔会被误报。通常使用 **MinGW64** 编译比使用 MSVC 编译更容易被误报。建议向杀毒软件厂商提交白名单，或尝试不使用单文件模式（即只用 ''--standalone''）。

===== 6. 总结建议 =====

为了获得**最强的加密性**和**稳定性**，推荐的生产环境命令组合：

<code bash>
nuitka --standalone --onefile \
       --windows-disable-console \
       --enable-plugin=pyside6 \
       --lto=no \
       --show-progress \
       main.py
</code>
//注意：根据你的实际 GUI 框架修改 plugin 参数。//