一、背景

在开发 Python Tkinter GUI 工具时，最终需要将程序交付给非技术用户使用。直接要求用户安装 Python 环境并不现实，因此需要将程序打包为独立的 Windows 可执行文件（.exe）。PyInstaller 是目前最常用的 Python 打包工具之一。

二、安装 PyInstaller

使用 pip 安装即可：

pip install pyinstaller

三、基本打包命令

假设主程序文件为 app.py，常用的打包命令如下：

# 打包为单文件，带 GUI 窗口（无控制台黑框）
pyinstaller --onefile --windowed app.py

# 打包为单文件，带控制台（调试用）
pyinstaller --onefile --console app.py

# 指定图标
pyinstaller --onefile --windowed --icon=app.ico app.py

常用参数说明

  • --onefile 或 -F：打包为单个 exe 文件
  • --windowed 或 -w：不显示控制台窗口（适用于 GUI 程序）
  • --console 或 -c：显示控制台窗口（适用于命令行程序）
  • --icon 或 -i：指定 exe 图标文件
  • --add-data：添加额外的数据文件（图片、配置等）
  • --name：指定输出的 exe 文件名

四、添加资源文件

如果程序依赖额外的图片、配置文件等资源，需要使用 --add-data 参数：

# Windows 下用分号分隔
pyinstaller --onefile --windowed \
  --add-data "assets;assets" \
  --add-data "config.json;." \
  app.py

在代码中读取资源文件时，需要兼容打包后的路径：

import sys
import os

def resource_path(relative_path):
    """获取资源文件的绝对路径，兼容 PyInstaller 打包"""
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

# 使用示例
icon = resource_path(os.path.join("assets", "logo.png"))
关键点：PyInstaller 打包后，资源文件会被解压到 sys._MEIPASS 指向的临时目录中，与开发时的运行路径不同，必须使用 resource_path() 函数处理。

五、常见问题与解决方案

5.1 打包后程序闪退

这是最常见的问题。解决方法：先用 --console 模式打包，在控制台中运行查看错误信息，修复后再用 --windowed 重新打包。

5.2 杀毒软件误报

PyInstaller 打包的单文件 exe 经常被杀毒软件误报为病毒。解决方案：

  • 使用 --onedir（目录模式）代替 --onefile，误报概率大幅降低
  • 对 exe 进行数字签名
  • 将 exe 提交到杀毒软件白名单

5.3 文件体积过大

如果打包后的 exe 体积很大，通常是因为包含了不必要的依赖。可以使用虚拟环境只安装必要的包：

# 创建干净的虚拟环境
python -m venv build_env
# 激活后只安装必要的依赖
pip install pyinstaller tkinter  # 以及项目必需的包

六、总结

PyInstaller 是将 Python GUI 程序交付给最终用户的有效工具。掌握资源文件路径处理、调试技巧和体积优化方法，可以显著提高打包的成功率和用户体验。建议在项目初期就考虑打包需求，避免后期出现路径依赖问题。