本文目录导读：
是的，PyInstaller 是目前最流行、最推荐的 Python 打包工具之一，它可以将 Python 脚本（以及它依赖的库、解释器）打包成一个独立的可执行文件（EXE），让没有安装 Python 的用户也能直接运行。
以下是关于使用 PyInstaller 打包的详细指南：
安装 PyInstaller
使用 pip 安装：
pip install pyinstaller
如果需要打包 GUI 程序（如 Tkinter、PyQt、PySide），建议先安装 pywin32 以获得更好的兼容性：
pip install pywin32
基本打包命令
最简单的打包（生成单个 EXE 文件）
pyinstaller -F your_script.py
-F：生成单个可执行文件,所有依赖都打包在一起。- 生成的 EXE 位于
dist文件夹下。
生成带控制台窗口的 EXE（适用于命令行程序）
pyinstaller -F your_script.py
默认就会生成控制台窗口（黑框），如果你的程序是 GUI 程序（没有控制台），可以加上 -w 参数：
pyinstaller -F -w your_gui_script.py
给 EXE 指定图标
pyinstaller -F -i icon.ico your_script.py
设置 EXE 的名称
pyinstaller -F -n MyApp your_script.py
常用参数详解
| 参数 | 完整形式 | 说明 |
|---|---|---|
-F |
--onefile |
打包成单个 EXE 文件 |
-D |
--onedir |
打包成一个文件夹（默认模式） |
-w |
--windowed |
不显示控制台窗口（适合 GUI 程序） |
-i |
--icon |
指定图标文件 (.ico) |
-n |
--name |
指定生成的 EXE 名称 |
--add-data |
添加额外文件或文件夹（使用 分隔源和目标） | |
--hidden-import |
强制包含某个模块（用于自动检测遗漏的依赖） | |
--exclude-module |
排除不需要的模块（减小体积） | |
--clean |
清理临时文件（构建前） | |
--debug |
生成调试版本 |
处理常见问题
问题：打包后运行报错“模块未找到”
解决方法：
pyinstaller -F --hidden-import missing_module your_script.py
或者创建一个 .spec 文件手动添加隐藏导入：
pyinstaller your_script.py
然后编辑生成的 your_script.spec 文件，在 Analysis 部分的 hiddenimports 列表中添加模块名,再执行：
pyinstaller your_script.spec
问题：打包后文件体积过大（通常几十 MB）
- 原因：PyInstaller 会包含整个 Python 解释器和所有依赖。
- 解决方法：
- 使用
--exclude-module排除不用的模块（如tkinter、test、distutils等）。 - 考虑使用 UPX（Ultimate Packer for Executables）压缩 EXE。
- 使用虚拟环境（venv）只安装必要库后再打包。
- 使用
问题：如何添加数据文件（如图片、配置文件）
在命令行中使用 --add-data：
pyinstaller -F --add-data "myimage.png;." your_script.py
注意：Windows 下用 分隔源和目标路径，Linux 下用 。
在代码中访问打包后的资源时,需要这样写：
import sys
import os
def resource_path(relative_path):
""" 获取资源的绝对路径，兼容开发和打包后 """
try:
# PyInstaller 会创建临时文件夹存储资源
base_path = sys._MEIPASS
except Exception:
base_path = os.path.abspath(".")
return os.path.join(base_path, relative_path)
# 使用方式
image_path = resource_path("myimage.png")
创建高级打包配置（使用 .spec 文件）
如果你有很多参数或需要复杂配置，建议使用 .spec 文件：
-
生成 .spec 文件：
pyi-makespec your_script.py -F -w -i icon.ico
-
编辑
.spec文件，添加隐藏导入、数据文件、排除模块等。 -
使用 .spec 文件打包：
pyinstaller your_script.spec
终极建议
- 使用虚拟环境：在干净的虚拟环境（venv）中安装项目所需的库，然后打包，这样可以避免打包不必要的库,显著减小体积。
- 测试：打包后的 EXE 要在 不同电脑上测试（尤其是没有 Python 的电脑）。
- 防误报：PyInstaller 打包的 EXE 有时会被杀毒软件误报（因为它是加壳的），可以尝试使用 UPX 压缩或报告给杀毒软件厂商。
| 场景 | 推荐命令 |
|---|---|
| 普通命令行程序 | pyinstaller -F your_script.py |
| GUI 程序（无控制台） | pyinstaller -F -w your_script.py |
| 程序需要额外文件 | pyinstaller -F --add-data "data/*;data/" your_script.py |
| 有图标 | pyinstaller -F -i icon.ico your_script.py |
| 调试隐藏导入问题 | pyinstaller -F --hidden-import module your_script.py |
| 极致减小体积 | 使用虚拟环境 + --exclude-module + UPX |
PyInstaller 是打包 Python 到 EXE 的事实标准，虽然生成的体积稍大，但兼容性好，基本能解决 95% 以上的需求，如果遇到极个别库不兼容的情况，可以考虑 Nuitka 或 cx_Freeze 作为备选方案。
