在 macOS M1 上使用 Nuitka 构建 Windows 可执行程序

学习笔记
1

在 macOS M1 上使用 Nuitka 构建 Windows 可执行程序，需要使用 跨平台编译工具链（Cross Compilation）。以下是详细步骤：

1. 安装依赖环境

安装 Homebrew（如果未安装） 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装 MinGW-w64 工具链

MinGW-w64 提供跨平台编译工具链：

brew install mingw-w64

2. 安装 Nuitka 

pip install nuitka

3. 配置跨平台编译环境

步骤 1: 设置编译目标为 Windows 

export PATH=$(brew --prefix mingw-w64)/bin:$PATH

步骤 2: 检查工具链是否可用 

x86_64-w64-mingw32-gcc --version

如果输出版本信息，则工具链安装成功。

4. 使用 Nuitka 编译 Windows 可执行程序

示例命令：构建 Windows 程序 

python -m nuitka --onefile --standalone --follow-imports \
    --mingw64 --windows-dependency-tool=pefile \
    --windows-icon-from-ico=app.ico \
    --output-dir=output \
    src/main.py

参数解释：

  • --onefile：打包成单个可执行文件。
  • --standalone：包含所有依赖项，生成独立文件夹或可执行文件。
  • --follow-imports：自动跟踪和包含所有导入模块。
  • --mingw64：启用跨平台编译，目标是 Windows 64 位平台。
  • --windows-dependency-tool=pefile：Windows 二进制依赖管理。
  • --windows-icon-from-ico：指定 Windows 图标文件。
  • --output-dir=output：设置输出目录。

5. 测试输出的 Windows 程序

编译完成后，你会在 output 目录下找到 main.exe 文件。
将此文件传输到 Windows 环境进行测试。

6. 注意事项

  1. Playwright 特殊处理
    如果项目使用 Playwright 或其他包含非 Python 文件的依赖，请确保将依赖资源目录打包到 Windows 可执行程序中：

    python -m nuitka --onefile --standalone --follow-imports \
    --include-data-dir=/Users/seveniruby/.cache/ms-playwright=ms-playwright \
    src/main.py

  2. 库兼容性问题
    某些 Python 库可能包含基于平台的动态链接库（.so 或 .dll 文件），需要确保这些依赖可以被正确包含。可使用 --include-data-files 指定外部依赖。

  3. 测试环境兼容性
    打包的程序需要在 Windows 上实际运行测试，检查是否有缺失依赖或兼容性问题。

  4. Python 版本一致性
    Nuitka 编译的程序需要在与目标平台相同的 Python 版本上运行。如果目标机器上的 Python 环境不同，可能需要调整编译设置或使用虚拟环境。

7. 常见问题解决

  1. ImportError: DLL load failed

    • 确保所有依赖库被正确打包，可添加 --include-package=package_name 强制包含特定库。

  2. 缺少 Playwright 浏览器依赖

    • 将浏览器缓存目录打包进去：
      --include-data-dir=/Users/seveniruby/.cache/ms-playwright=ms-playwright

  3. 构建失败或无法识别 Windows 工具链

    • 确认 MinGW 编译器路径正确设置：
      echo $PATH
    • 检查 x86_64-w64-mingw32-gcc 命令是否可用。

总结

在 macOS M1 上通过 MinGW-w64 实现跨平台编译，Nuitka 可以顺利将 Python 项目打包成 Windows 可执行文件。确保所有依赖项（包括非 Python 文件）都正确包含后，可将最终结果直接拷贝到 Windows 环境运行测试。如果有其他问题，欢迎继续讨论！