PyInstaller 使用教程 (Python 打包指南)

PyInstaller 是一个非常流行的 Python 打包工具，它可以将 Python 脚本及其依赖项打包成一个独立的可执行文件（如 Windows 下的 .exe），使得在没有安装 Python 环境的机器上也能运行程序。

在开始之前，建议创建一个干净的虚拟环境，以避免打包不必要的库，从而减小文件体积。

在终端（CMD 或 PowerShell）中执行以下命令：

pip install pyinstaller

若需升级到最新版本：

pip install --upgrade pyinstaller

假设您的入口脚本名为 main.py。

pyinstaller main.py

执行后，会生成两个文件夹（build 和 dist）和一个文件（main.spec）。

• dist/main/ 文件夹中包含可执行文件和所有依赖文件。
• 运行 dist/main/main.exe 即可启动程序。

如果您希望只有一个独立的 .exe 文件，使用 -F 参数：

pyinstaller -F main.py

• 生成的文件位于 dist/main.exe。
• 注意：单文件启动速度稍慢，因为运行时需要解压临时文件。

下表列出了最常用的命令行参数：

示例：打包一个带图标的 GUI 程序

pyinstaller -F -w -i "logo.ico" -n "我的爬虫工具" main.py

如果您的代码中读取了外部文件（如 config.yaml 或图片），打包后可能会报错“找不到文件”。这是因为打包后的运行路径发生了变化。

在 Python 代码中，需要使用以下函数来获取资源的绝对路径：

import sys
import os
 
def resource_path(relative_path):
    """ 获取资源绝对路径，适用于开发环境和 PyInstaller 打包后的环境 """
    if hasattr(sys, '_MEIPASS'):
        # PyInstaller 打包后，文件会被解压到 sys._MEIPASS 临时目录
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)
 
# 使用示例
config_path = resource_path("config.yaml")

使用 –add-data 将文件包含进去。注意 Windows 使用分号 ; 分隔。

# 格式: --add-data "源文件;打包后的内部路径"
pyinstaller -F --add-data "config.yaml;." main.py

第一次运行 PyInstaller 命令后，会自动生成一个 name.spec 文件。您可以直接编辑这个文件来管理复杂的打包配置，而不需要每次都敲很长的命令。

编辑 main.spec 文件中的 Analysis 部分：

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[('config.yaml', '.'), ('images/', 'images/')], # 在这里添加资源文件
    hiddenimports=['pandas'], # 在这里手动添加未被识别的库
    ...
)

使用 Spec 文件打包：

pyinstaller main.spec

现象：报错 UnicodeDecodeError 或构建中断。 解决：

1. 确保项目路径全英文，且无空格。
2. 尽量不要把项目放在层级过深的目录（如 E:\工作\2025\项目\…\）。
3. 建议移动到 C:\Build\Project 目录下进行打包。

现象：打包成功，但运行时提示找不到某个库（常见于 pandas, numpy 或动态导入的库）。 解决：

1. 使用 –hidden-import 参数手动指定：

    pyinstaller -F --hidden-import=pandas._libs.tslibs.base main.py
 

1. 或者在 spec 文件的 hiddenimports 列表中添加。

现象：一个简单的脚本打包后有几百 MB。 解决：

1. 使用虚拟环境：这是最主要的原因。如果在全局环境打包，PyInstaller 可能会把 Anaconda 中所有无关的库都打进去。
2. 使用 pipenv 或 venv 创建纯净环境，只安装必要的库。
3. 排除不需要的模块：–exclude-module matplotlib。

现象：打包出的 exe 被 Windows Defender 或 360 删除。 解决：

1. 这是 PyInstaller 的已知问题（Bootloader 特征码）。
2. 尝试重新编译 PyInstaller 的 Bootloader（较复杂）。
3. 或者向杀毒软件厂商提交误报申诉。
4. 尝试使用 Nuitka 作为替代方案（虽然 Nuitka 配置更难，但被杀毒软件拦截的概率较低）。

1. 简单脚本：直接用 pyinstaller -F main.py。
2. GUI 程序：加上 -w 去除黑框。
3. 复杂项目：学会修改和使用 .spec 文件。
4. 切记：保持路径纯净（无中文、无空格），使用虚拟环境。