🧩 Python 程序打包成 EXE 全面教程
📖 一、PyInstaller 简介
PyInstaller 是最常用的 Python 程序打包工具，可以将 .py 文件及其所有依赖打包成一个可在 Windows 上独立运行的 .exe 文件。
特点：
- 支持所有主流 Python 版本（3.7+）
- 无需安装 Python 即可运行打包后的程序
- 可打包为单个文件或文件夹结构
- 支持添加图标、资源文件、隐藏命令行窗口等
⚙️ 二、环境准备
1️⃣ 检查 Python 环境
在命令行输入：
python --version输出类似：
Python 3.10.13确保系统能正确识别 Python。
2️⃣ 安装 PyInstaller
pip install pyinstaller验证安装是否成功：
pyinstaller --version🧱 三、示例项目结构
假设你的项目如下：
project/
│
├─ main.py # 主程序
├─ config/
│ └─ settings.json # 配置文件
└─ images/
└─ logo.png # 图片资源main.py 示例代码：
import json, os, sys
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)
def main():
config_path = resource_path("config/settings.json")
with open(config_path, "r", encoding="utf-8") as f:
data = json.load(f)
print("配置文件内容：", data)
input("按回车退出...")
if __name__ == "__main__":
main()🚀 四、打包命令详解
🔹 最简单的打包
pyinstaller main.py输出目录结构：
build/ # 中间构建文件
dist/ # 最终生成的可执行文件所在目录
main.spec # PyInstaller 配置文件进入 dist/main/，可看到：
main.exe🔹 打包成单个 .exe 文件
pyinstaller -F main.py
-F表示 onefile 模式，将所有依赖打包进单个文件中。
输出结果：
dist/main.exe🔹 添加程序图标
pyinstaller -F -i icon.ico main.py图标文件必须是
.ico格式（可用在线转换工具把.png转成.ico）。
🔹 去除命令行黑框（GUI 程序用）
pyinstaller -F -w main.py
-w或--windowed表示 隐藏控制台窗口。
用于 PyQt5、Tkinter、wxPython 等图形界面应用。
🔹 自定义生成文件名与输出路径
pyinstaller -F -w -i app.ico -n myApp --distpath build_output main.py参数说明：
-n myApp：自定义可执行文件名。--distpath：指定输出文件夹（默认是dist）。
🔹 打包时包含资源文件
pyinstaller -F main.py --add-data "config;config" --add-data "images;images"解释：
"源路径;目标路径"- Windows 用分号
;，Linux/WSL 用冒号:
打包后：
dist/main.exe运行时即可自动包含 config/settings.json 和 images/logo.png。
🧩 五、完整打包命令示例
pyinstaller -F -w -i app.ico -n TrafficMonitor ^
--add-data "config;config" --add-data "images;images" ^
main.py运行完毕后：
dist/TrafficMonitor.exe双击即可运行（无黑框）。
⚡ 六、打包后优化与问题处理
🔸 文件体积太大？
可以用 UPX 压缩：
# 安装 UPX（可选）
pip install upx
# 或手动下载：https://upx.github.io/
pyinstaller -F main.py --upx-dir "C:\path\to\upx"🔸 运行时报错：找不到模块
添加隐藏导入模块：
pyinstaller -F main.py --hidden-import <模块名>🔸 资源文件路径问题
使用下面的函数来获取资源路径（推荐放在开头）：
import sys, 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)这样在 .exe 中也能正确找到资源。
🧠 七、使用 .spec 文件自定义打包流程
第一次运行 PyInstaller 时会生成 main.spec 文件，内容类似：
# main.spec
a = Analysis(
['main.py'],
pathex=[],
binaries=[],
datas=[('config/settings.json', 'config')],
hiddenimports=[],
)
exe = EXE(
a.scripts,
a.binaries,
a.zipfiles,
a.datas,
name='MyApp',
console=False, # False 表示不显示控制台
icon='app.ico'
)之后可以直接运行：
pyinstaller main.spec这样不必每次输入长长的命令，适合项目固定打包需求。
🔍 八、完整流程总结
| 步骤 | 命令 | 说明 |
|---|---|---|
| 1️⃣ 安装 PyInstaller | pip install pyinstaller |
准备工具 |
| 2️⃣ 编写代码 | main.py |
确保能独立运行 |
| 3️⃣ 测试运行 | python main.py |
确认无报错 |
| 4️⃣ 打包命令 | pyinstaller -F -w main.py |
一键生成 exe |
| 5️⃣ 添加资源 | --add-data "config;config" |
打包额外文件 |
| 6️⃣ 添加图标 | -i icon.ico |
美化图标 |
| 7️⃣ 生成文件 | 查看 dist/ 目录 |
直接运行 exe |
| 8️⃣ 优化 | 使用 UPX 压缩 | 减小体积 |
🧰 九、进阶技巧
批处理打包脚本（保存为
build.bat）：@echo off echo === 开始打包 === pyinstaller -F -w -i app.ico -n MyApp --add-data "config;config" main.py echo === 打包完成，生成文件在 dist/MyApp.exe === pause双击
build.bat即可一键生成。
✅ 十、示例打包结果
成功后会生成：
dist/
└── MyApp.exe双击即可直接运行，即使目标计算机上没有安装 Python。
