Python 代码打包为 exe 全攻略：6 种主流方法及避坑指南

常见坑与解决方案

• 缺少模块（ModuleNotFoundError） → 加 --hidden-import=模块名 或修改 .spec 文件
• 图片、配置文件找不到 → 使用 sys._MEIPASS 获取临时解压路径

import sys
import os

def resource_path(relative_path):
    """获取资源绝对路径（打包前后兼容）"""
    base_path = getattr(sys, '_MEIPASS', os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)

• 文件体积过大 → 使用 UPX 压缩（--upx-dir）或排除不必要的依赖
• 杀毒软件误报 → 正常现象，建议用 --onedir 模式或提交白名单

2. Nuitka（性能更好、体积更小）

原理 把 Python 代码翻译成 C 代码，再编译成机器码。 不依赖 Python 解释器，启动速度快，体积相对较小。

基本步骤

# 安装（推荐使用最新版）
pip install -U nuitka

# 推荐打包命令
python -m nuitka \
    --standalone \
    --onefile \
    --windows-disable-console \
    --include-data-dir=images=images \
    --plugin-enable=pylint-warnings \
    --windows-icon-from-ico=app.ico \
    your_script.py

优点对比 PyInstaller

• 启动速度明显更快（接近原生 C 程序）
• 最终文件体积通常更小
• 不需要解压到临时目录

缺点

• 编译时间较长（首次几分钟）
• 对一些动态特性（eval、exec、某些 metaclass）支持不完美

3. PyOxidizer（现代化、启动最快）

原理 使用 Rust 编写，把 Python 解释器 + 代码嵌入到一个原生可执行文件中，几乎无解压开销。

基本步骤（2025 年推荐方式）

1. 安装 PyOxidizer

pip install pyoxidizer

2. 创建项目

pyoxidizer init-executable myapp
cd myapp

3. 编辑 pyoxidizer.bzl（配置文件）
4. 构建

pyoxidizer build

特点

• 启动速度极快（几乎无冷启动延迟）
• 支持嵌入资源、自定义 Python 解释器
• 适合追求极致体验的桌面应用

缺点

• 配置相对复杂
• 社区规模小于 PyInstaller

4. 快速对比总结表

5. 通用避坑指南

1. 路径问题（最常见坑）
   • 永远不要用相对路径
   • 使用 resource_path() 函数（见 PyInstaller 示例）
2. 第三方库兼容性
   • PyQt5/PySide6 → 必须加 --hidden-import
   • pandas/numpy → 通常自动识别，但有时需加 --include-data-dir
   • tkinter → PyInstaller 一般没问题，Nuitka 需要额外配置
3. 图标不生效
   • 必须是 .ico 格式（Windows）
   • 建议 256×256 多尺寸 ico 文件
4. 杀毒报毒
   • 单文件模式最容易被报
   • 建议用 --onedir 模式分发，或提交给杀毒厂商加白
5. 版本管理
   • 建议用虚拟环境打包
   • 记录 requirements.txt 和 Python 版本
6. 测试建议
   • 在干净的 Windows 虚拟机上测试（无 Python 环境）
   • 测试不同杀毒软件的表现

总结：打包推荐策略

• 普通脚本 / 小工具 → PyInstaller 单文件
• 对启动速度有要求 → Nuitka（强烈推荐）
• 追求极致现代化 → PyOxidizer
• 命令行工具给别人用 → Shiv / PEX
• 老项目兼容 → cx_Freeze 或 py2exe