Python脚本打包成exe：PyInstaller基础命令与快速上手

一、准备工作：虚拟环境搭建与依赖安装

在直接运行打包命令前，最关键但常被忽略的步骤是控制依赖边界。PyInstaller 在分析项目时，会扫描当前 Python 环境已安装的库。若在包含大量科研库或综合工具的全局环境中打包，即便脚本仅有十行，也会将不相关的模块和二进制 DLL 打包进产物，导致生成的文件体积动辄数百兆，启动缓慢。

1. 创建纯净的 Python 虚拟环境

推荐为每个独立打包项目建立专属虚拟环境，只安装脚本必需的第三方库：

# 1. 在项目根目录下创建虚拟环境 .venv
python -m venv .venv

# 2. 激活虚拟环境 (Windows PowerShell)
.venv\Scripts\Activate.ps1
# 若使用 CMD 终端，则执行：
# .venv\Scripts\activate.bat

# 3. 安装 PyInstaller 工具
pip install pyinstaller

2. 编写验证脚本

以一个标准交互脚本 app.py 为例。该脚本读取命令行参数并执行基本计算：

# 文件名：app.py
import sys
import time

def main():
    print("=" * 40)
    print("PyInstaller 基础打包示例程序已启动")
    print("=" * 40)
    name = input("请输入您的使用者名称：")
    print(f"你好，{name}！当前 Python 运行时主版本为：{sys.version_info.major}.{sys.version_info.minor}")
    print("程序执行完毕，将在 3 秒后自动关闭...")
    time.sleep(3)

if __name__ == "__main__":
    main()

在打包前，必须确保 python app.py 在当前环境中能够无误执行。打包本身不会修复代码层面的逻辑错误与语法缺陷。

二、核心命令与两种打包模式深度解析

PyInstaller 的基本调用形式为 pyinstaller [参数] 脚本名.py。初学者常困惑于为何有时产出单个庞大的 .exe，有时产出一个包含大量 .dll 文件的目录。这由核心选项 -F 与 -D 决定。

1. 模式选择策略

• 使用 -F（单文件）： 适合轻量控制台工具、单文件小脚本、需要通过微信或钉钉直接传给同事执行的便捷应用。
• 使用 -D（单目录）： 适合包含大量图片/音视频素材、模型文件、或依赖庞大框架（如 PyTorch、TensorFlow、OpenCV）的工程。单目录模式避免了启动时数秒甚至十秒的解压时间。

2. 高频参数矩阵与说明

三、实战上手：打包并运行你的第一个可执行文件

下面按照实际操作步骤，将前文编写的 app.py 打包为单文件。

1. 执行打包命令

# 确保终端当前位于项目根目录，且虚拟环境处于激活状态
pyinstaller -F app.py

520 INFO: PyInstaller: 6.5.0
521 INFO: Python: 3.11.8 (venv)
...
1540 INFO: Analyzing app.py
2890 INFO: Looking for dynamic libraries
3410 INFO: Building PKG (CArchive) app.pkg
4820 INFO: Building EXE from EXE-00.toc
5130 INFO: Appending PKG archive to EXE
5210 INFO: Fixing EXE
5280 INFO: Building EXE `dist\app.exe` completed successfully.

2. 产物目录结构说明

打包完成后，项目根目录会新增三个关键内容：

• dist/（分发目录）： 最终交付给用户的 app.exe 就位于此目录。若使用 -D 模式，则是同名文件夹。
• build/（构建中间目录）： 存放打包过程中的编译日志、临时分析表和二进制缓存。打包成功后可以安全删除，若后续不再修改 spec 文件，可随时清空。
• app.spec（打包规范说明书）： PyInstaller 首次运行时自动生成的 Python 配置文件。它记录了所有依赖项、打包参数与钩子脚本。熟练后可直接修改此文件并通过 pyinstaller app.spec 重复构建。

3. 验证运行结果

在终端中切入 dist 目录执行产物：

cd dist
.\app.exe

========================================
PyInstaller 基础打包示例程序已启动
========================================
请输入您的使用者名称：DemoUser
你好，DemoUser！当前 Python 运行时主版本为：3.11
程序执行完毕，将在 3 秒后自动关闭...

四、避坑指南：初学者四大高频报错与解决决策

打包 Python 程序的难点通常不在于命令本身，而在于打包后在脱机环境运行时的兼容性问题。以下是排查频率最高的四类故障及对应的解决原则。

1. 现象一：双击 exe 瞬间闪退，甚至无任何提示

这是初学者遇到频率最高的现象。原因：若程序末尾没有阻塞语句（如 input()），程序执行完毕即正常退出；或者程序在启动加载模块阶段崩溃抛出了异常，Windows 自动关闭了子进程控制台。

2. 现象二：运行时抛出 ModuleNotFoundError

虽然本地执行 python app.py 完全正常，但打包为 exe 后提示找不到某个库。

原因：PyInstaller 默认通过静态代码抽象语法树（AST）扫描 import 声明。如果某些库采用了动态导入（例如 __import__()、importlib.import_module()），PyInstaller 无法通过静态分析识别到该依赖，因而没有将其打包进 exe。

解决方案：在打包命令中显式补充 --hidden-import 参数：

pyinstaller -F --hidden-import="pkg_resources" --hidden-import="pydantic" app.py

3. 现象三：找不到外部图片、音频或配置文件

在 -F（单文件）模式下，程序启动时会将打包的所有资源解压到操作系统的临时目录（例如 C:\Users\用户名\AppData\Local\Temp\_MEIxxxxxx）。如果代码中使用的是相对路径 open("config.json")，程序会在当前运行的终端目录寻找，而不是解包目录，从而引发 FileNotFoundError。

标准解决方案：使用 PyInstaller 官方推荐的通用资源寻址函数：

import sys
import os

def get_resource_path(relative_path):
    """ 获取静态资源绝对路径，兼容开发环境与 PyInstaller 单文件打包环境 """
    if hasattr(sys, '_MEIPASS'):
        # PyInstaller 单文件运行时的解压临时根路径
        base_path = sys._MEIPASS
    else:
        # 本地开发时的当前脚本路径
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

# 使用示例
config_path = get_resource_path("config.json")
with open(config_path, "r", encoding="utf-8") as f:
    config_content = f.read()

同时，在打包时通过 --add-data 将文件打入：

pyinstaller -F --add-data "config.json;." app.py

五、总结

使用 PyInstaller 打包 Python 脚本并不复杂，其核心关键在于遵循以下三条工程原则：

1. 依赖先行：始终在独立的纯净虚拟环境中打包，将不相关的臃肿包隔绝在外。
2. 模式清晰：单工具交付优先使用 -F，包含繁多静态资产与大型计算框架的项目优先使用 -D。
3. 科学排障：遇到问题先在命令行终端运行 exe 抓取错误堆栈，根据报错补充 --hidden-import 或规范化 sys._MEIPASS 静态资源路径。