Python 代码打包为 EXE 完整指南与常见问题排查

针对复杂项目（如带资源文件、依赖缺失），需要通过参数或 spec 文件进行优化。

解决依赖缺失问题

PyInstaller 有时无法自动识别某些依赖（如 Pillow 的子模块），导致运行时报错'找不到模块'。此时需要在命令行添加 --hidden-import 参数：

pyinstaller -F -w --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py

该参数可以重复使用，将所有未被识别的依赖模块都加上。

自定义 EXE 图标

给 EXE 添加个性化图标能让软件看起来更专业。图标必须是 .ico 格式，推荐尺寸 256x256。

1. 准备 .ico 图标文件（可用在线工具转换 PNG/JPG）；
2. 将图标放在代码目录下（与 main.py 同级）；
3. 执行打包命令并添加 -i 参数：

pyinstaller -F -w -i app.ico main.py

处理资源文件

如果项目引用了本地资源（如图标、配置文件），打包时需指定路径，否则运行时可能找不到文件。

命令行方式（简单场景）

通过 --add-data 参数添加资源文件，注意分隔符在不同系统下不同（Windows 用分号 ;，Mac/Linux 用冒号 :）：

pyinstaller -F -w --add-data "static;static" main.py

这表示将本地的 static 文件夹打包到 EXE 同级的 static 文件夹中。

复杂场景：使用 Spec 文件

当命令行参数无法满足需求（如多资源文件、压缩优化）时，建议修改自动生成的 .spec 文件。

1. 生成 spec 文件：

   pyinstaller -D main.py
   

   这会生成一个 main.spec 文件。

2. 编辑 spec 文件： 用文本编辑器打开 main.spec，找到 Analysis 和 EXE 部分进行修改。以下是核心配置示例：

# -*- mode: python ; coding: utf-8 -*-
block_cipher = None

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[('static', 'static')],
    hiddenimports=['PIL.Image', 'PIL.ImageTk'],
    hookspath=[],
    excludes=[],
    cipher=block_cipher,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='图片分类工具',
    debug=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,
    icon='app.ico',
)

3. 基于 spec 文件打包： 修改完成后，执行以下命令（注意参数是 spec 文件）：

pyinstaller main.spec

常见问题排查

错误：Icon input file not found

• 原因：指定的 .ico 图标文件不存在。
• 解决：检查文件名是否正确，或将图标文件放到代码目录下。

错误：找不到模块 XXX（ModuleNotFoundError）

• 原因：PyInstaller 未自动识别依赖。
• 解决：在命令行添加 --hidden-import=模块名，或在 spec 文件的 hiddenimports 中添加。

EXE 启动后闪退

• 原因：代码报错但 -w 参数隐藏了命令行窗口，看不到错误信息。
• 解决：去掉 -w 参数重新打包，运行时会弹出命令行窗口，根据报错修复代码（如路径错误或依赖缺失）。

EXE 体积过大

• 原因：打包了 Python 标准库及无用依赖。
• 优化方案：
  1. 启用 UPX 压缩（在 spec 文件中设置 upx=True，需提前安装 UPX 工具）；
  2. 在 spec 文件的 excludes 中排除无用模块（如 excludes=['unittest']）；
  3. 避免引入 numpy 等大体积依赖，必要时使用虚拟环境隔离。

运行 EXE 提示'找不到资源文件'

• 原因：资源文件未正确打包。
• 解决：
  1. 使用 --add-data 参数指定路径；
  2. 代码中使用绝对路径访问资源，或通过 sys._MEIPASS 获取打包后的资源路径。

最终推荐命令

结合本文 GUI 项目（依赖 Pillow、需隐藏命令行、自定义图标），推荐命令如下：

pyinstaller -F -w -i app.ico --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py

若无图标需求，可简化为：

pyinstaller -F -w --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py

总结

PyInstaller 是 Python 打包的首选工具。基础命令可快速生成 EXE，Spec 文件则能实现精细化配置。记住几个核心要点：

1. 打包前先确保项目能正常运行；
2. GUI 项目务必加 -w 参数隐藏命令行窗口；
3. 遇到依赖缺失用 --hidden-import 补充；
4. 遇到问题先去掉 -w 参数查看具体报错信息。