本文档旨在指导开发者如何使用 PyInstaller 工具将基于 Python 和 Kivy 框架开发的应用程序打包成独立的可执行文件（.exe）。我们将详细介绍 PyInstaller 的安装、`.spec` 文件的创建与配置、版本文件的编写，以及最终的编译步骤，帮助你解决打包过程中可能遇到的问题。
使用 PyInstaller 打包 Kivy 应用
将 Python 和 Kivy 应用打包成可执行文件，可以使用 PyInstaller 这个强大的 Python 库。 它能够将 Python 脚本及其依赖项打包成一个独立的 .exe 文件，方便用户在没有 Python 环境的机器上运行。
安装 PyInstaller
首先，你需要安装 PyInstaller。打开你的终端或命令提示符，并输入以下命令：
pip install pyinstaller
这条命令会从 Python 包索引（PyPI）下载并安装 PyInstaller 及其依赖项。
创建并配置 .spec 文件
.spec 文件是 PyInstaller 的配置文件，用于指定打包过程中的各种参数，例如主程序入口、依赖项、资源文件等。
-
生成 .spec 文件
在你的项目目录下，打开终端或命令提示符，并输入以下命令：
pyi-makespec your_main_file.py
将 your_main_file.py 替换为你的主程序文件名。这条命令会在当前目录下生成一个名为 your_main_file.spec 的文件。
-
编辑 .spec 文件
使用文本编辑器打开生成的 .spec 文件。你需要修改以下几个关键部分：
-
Analysis 部分：
- ['your_main_file.py']: 确保这里是你的主程序文件名。如果你的主程序文件位于上一级目录，则需要写成['../your_main_file.py']。
- pathex=[]: 指定搜索模块的路径。如果你的项目依赖于不在标准库中的模块，需要将它们的路径添加到这里。
- datas=[("../your_folder","your_folder"),("../your_file.ext",".")]: 指定需要包含的非 Python 文件，例如图片、字体、配置文件等。 第一个参数是源文件/文件夹的路径，第二个参数是目标路径（相对于生成的可执行文件）。 如果你的文件夹位于上一级目录，则需要写成datas=[("../../your_folder","your_folder"),("../../your_file.ext",".")]。
- hiddenimports=["tkinter"]: 指定需要显式导入的模块。有些模块可能不会被 PyInstaller 自动检测到，需要手动添加到这里。 例如在打包matplotlib的时候，需要添加"matplotlib.backends.backend_tkagg"
-
EXE 部分：
- name='YourAppName': 指定生成的可执行文件的名称。
- version="version.txt": 指定版本信息文件。
- *[Tree(p) for p in (sdl2.dep_bins + glew.dep_bins)]: 这行代码用于包含 Kivy 依赖的 SDL2 和 GLEW 库。
- console=False: 如果你的应用是 GUI 应用，不需要显示控制台窗口，可以将此值设置为 False。
- icon='../your_icon.ico': 指定应用程序的图标文件。如果你的icon文件位于上一级目录，则需要写成icon='../your_icon.ico'。
一个典型的 Kivy 应用的 .spec 文件可能如下所示：
# -*- mode: python ; coding: utf-8 -*- from kivy_deps import sdl2, glew from kivy.tools.packaging.pyinstaller_hooks import get_deps_minimal, get_deps_all, hookspath, runtime_hooks block_cipher = None a = Analysis( ['../your_main_file.py'], pathex=[], datas=[("../your_folder","your_folder"),("../your_file.ext",".")], hookspath=[], hooksconfig={}, runtime_hooks=[], win_no_prefer_redirects=False, win_private_assemblies=False, cipher=block_cipher, hiddenimports=["tkinter"], noarchive=False ) pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher) exe = EXE(pyz, a.scripts, a.binaries, a.zipfiles, a.datas, name='YourAppName', version="version.txt", *[Tree(p) for p in (sdl2.dep_bins + glew.dep_bins)], debug=False, strip=False, upx=True, runtime_tmpdir=None, console=False, icon='../your_icon.ico') -
创建版本信息文件 (version.txt)
版本信息文件用于设置应用程序的版本号、公司名称、版权信息等。创建一个名为 version.txt 的文件，并按照以下格式填写：
# UTF-8
#
# For more details about fixed file info 'ffi' see:
# http://msdn.microsoft.com/en-us/library/ms646997.aspx
VSVersionInfo(
ffi=FixedFileInfo(
# filevers and prodvers should be always a tuple with four items: (1, 2, 3, 4)
# Set not needed items to zero 0.
filevers=(1, 0, 0, 0),
prodvers=(1, 0, 0, 0),
# Contains a bitmask that specifies the valid bits 'flags'r
mask=0x3f,
# Contains a bitmask that specifies the Boolean attributes of the file.
flags=0x0,
# The operating system for which this file was designed.
# 0x4 - NT and there is no need to change it.
OS=0x4,
# The general type of file.
# 0x1 - the file is an application.
fileType=0x1,
# The function of the file.
# 0x0 - the function is not defined for this fileType
subtype=0x0,
# Creation date and time stamp.
date=(0, 0)
),
kids=[
StringFileInfo(
[
StringTable(
u'040904B0',
[StringStruct(u'CompanyName', u'Your company name'),
StringStruct(u'FileDescription', u'Your Filename'),
StringStruct(u'FileVersion', u'Your version number'),
StringStruct(u'InternalName', u'Your app name'),
StringStruct(u'LegalCopyright', u'Copyright (c) your company name'),
StringStruct(u'OriginalFilename', u'YourApp.exe'),
StringStruct(u'ProductName', u'YourApp'),
StringStruct(u'ProductVersion', u'4.2.0')])
]),
VarFileInfo([VarStruct(u'Translation', [1033, 1200])])
]
)根据你的应用信息修改文件中的字段。
运行 PyInstaller
完成 .spec 文件的配置后，就可以运行 PyInstaller 进行打包了。在终端或命令提示符中，输入以下命令：
pyinstaller your_main_file.spec
将 your_main_file.spec 替换为你的 .spec 文件名。PyInstaller 会根据 .spec 文件的配置，分析你的代码，收集依赖项，并将它们打包成一个可执行文件。
打包结果
打包完成后，会在你的项目目录下生成两个文件夹：dist 和 build。可执行文件位于 dist 文件夹中。根据 .spec 文件的配置，你可能会得到一个单独的可执行文件，或者一个包含所有依赖项的文件夹。
注意事项
- 依赖项问题： 如果你的应用依赖于一些特殊的库，PyInstaller 可能无法自动检测到。你需要在 .spec 文件的 hiddenimports 中显式地添加这些库。
- 资源文件问题： 确保你的资源文件（例如图片、字体）被正确地包含在 .spec 文件的 datas 中。
- 路径问题： 检查 .spec 文件中的所有路径是否正确。使用相对路径可以提高可移植性。
- Kivy 依赖： Kivy 应用通常依赖于 SDL2 和 GLEW 库。确保你的 .spec 文件中包含了这些库的依赖项。
- 控制台窗口： 如果你的应用是 GUI 应用，不需要显示控制台窗口，可以将 .spec 文件中的 console 设置为 False。
- 更新 Kivy 依赖： 如果在打包过程中遇到 No module named 'kivy_deps' 错误，尝试运行以下命令更新 Kivy 依赖：
pip install -U kivy_deps.sdl2 kivy_deps.glew
总结
使用 PyInstaller 可以方便地将 Python 和 Kivy 应用打包成可执行文件。通过正确地配置 .spec 文件，你可以控制打包过程的各个方面，确保你的应用能够顺利运行。 记住要仔细检查依赖项、资源文件和路径，并根据你的应用需求调整 .spec 文件的配置。
