PyInstaller 是一个功能强大的工具，能够将 Python 应用程序及其依赖项打包成可在 Windows、Linux 和 macOS 上运行的独立可执行文件。它支持 Python 3.6 至 3.10 版本，并能自动收集项目所需的库和资源，最终生成无需安装 Python 环境即可运行的程序。

安装 PyInstaller

通过 pip 可轻松安装 PyInstaller：

pip install pyinstaller

若需指定代理服务器，可使用如下命令：

pip install --proxy=http://your-proxy:port pyinstaller

安装完成后可通过以下命令查看版本信息：

pyinstaller --version

打包输出结构

执行打包命令后，默认会生成三个主要部分：

• .spec 文件：包含打包配置的脚本文件，可用于自定义构建流程。
• build/ 目录：存放编译过程中的临时文件，构建完成后可安全删除。
• dist/ 目录：最终生成的可执行文件所在目录，发布时使用此目录内容。

常用命令参数

以下是常用的构建选项说明：

参数	说明
--onefile 或 -F	生成单个可执行文件，所有依赖嵌入其中。
--onedir 或 -D	生成一个包含主程序和依赖库的文件夹（默认模式）。
--console 或 -c	启用控制台窗口，适用于命令行工具（默认）。
--windowed 或 -w	不显示控制台窗口，适合图形界面应用。
--icon=file.ico	为 Windows 可执行文件指定图标。
--name=AppName	设置生成的应用名称。
--add-data "src;dest"	添加非代码资源文件（如图片、配置文件），Windows 使用分号，其他系统用冒号。
--exclude-module mod_name	排除特定模块以减小体积。
--clean	清理缓存并重新构建，避免旧文件影响结果。
--noconfirm 或 -y	覆盖输出目录时不提示确认。

实际操作示例

假设有一个基于 Tkinter 的简单 GUI 脚本 app_gui.py：

import tkinter as tk
from tkinter import messagebox

class SimpleApp:
    def __init__(self):
        self.window = tk.Tk()
        self.window.title("测试应用")
        self.setup_ui()

    def setup_ui(self):
        label = tk.Label(self.window, text="请输入姓名：")
        label.pack(pady=5)

        self.entry = tk.Entry(self.window)
        self.entry.pack(pady=5)

        btn = tk.Button(self.window, text="打招呼", command=self.greet)
        btn.pack(pady=5)

    def greet(self):
        name = self.entry.get().strip() or "访客"
        messagebox.showinfo("问候", f"你好，{name}！")

    def run(self):
        self.window.mainloop()

if __name__ == "__main__":
    app = SimpleApp()
    app.run()

将其打包为无控制台窗口且带图标的单文件程序：

pyinstaller -F -w -i app_icon.ico --name=MyGreetingApp app_gui.py

构建成功后，在 dist/ 目录下将得到名为 MyGreetingApp.exe 的可执行文件。

调试与问题排查

若运行生成的程序立即退出，建议在终端中直接启动以查看错误输出：

dist\MyGreetingApp.exe

常见问题包括：

• 模块未找到（ImportError）：确保所有依赖已通过 pip 安装，特别是 IDE 自动管理的虚拟环境中缺失的包。
• 资源路径错误：当程序被打包后，原始文件路径失效。应使用 sys._MEIPASS 动态获取运行时资源路径：

import sys
import os

def resource_path(relative_path):
    """ 获取打包后资源的正确路径 """
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

跨平台注意事项

尽管 PyInstaller 支持多平台构建，但生成的可执行文件不具备跨平台兼容性。必须在目标操作系统上进行打包。例如，在 Windows 上生成的 .exe 文件无法在 Linux 或 macOS 上运行。

高级功能：字节码加密

为提高安全性，可对打包的 Python 字节码进行加密。需先安装 pycryptodome：

pip install pycryptodome

然后使用 --key 参数指定 16 位密钥：

pyinstaller --key=abcdef1234567890 app_gui.py

该功能可显著增加反编译难度，保护源码逻辑。

构建规范文件（.spec）的使用

首次打包时会自动生成 app_gui.spec 文件。后续可通过修改此文件实现更精细的控制，如添加数据文件、调整路径等：

# -*- mode: python -*-
block_cipher = None

a = Analysis(
    ['app_gui.py'],
    pathex=['.'],
    binaries=[],
    datas=[('config/', 'config'), ('images/logo.png', 'images')],
    hiddenimports=[],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='MyGreetingApp',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='app_icon.ico'
)

使用 spec 文件构建：

pyinstaller MyGreetingApp.spec

最佳实践建议

• 正式发布前，先以 --onedir 模式测试打包完整性。
• 避免源码路径中包含空格或特殊字符。
• 保持脚本编码为 UTF-8。
• 定期使用 --clean 清理缓存，防止构建异常。