本文介绍了使用 PyInstaller 将 Python 代码打包为 EXE 可执行文件的完整流程。涵盖环境准备、基础打包命令、依赖与资源优化配置、spec 文件精细化设置以及常见问题排查。重点讲解了隐藏命令行窗口、添加自定义图标、处理缺失模块及资源文件的方法，并提供了解决闪退和体积过大的具体方案，适合各类 Python 项目分发需求。
在 Python 开发完成后，为了方便非技术用户使用（无需安装 Python 环境），将代码打包为 EXE 可执行文件是常用需求。本文以 GUI 程序为例，详细介绍使用 PyInstaller 工具打包的完整流程、优化配置及常见问题解决方案，适合各类 Python 项目打包场景。
打开命令行（CMD/PowerShell），执行以下命令安装 PyInstaller：
pip install pyinstaller
pyinstaller --version，显示版本号即安装成功。确保项目所需依赖已安装（以本文 GUI 项目为例，依赖 Pillow 库）：
pip install pillow # 根据自己的项目修改依赖名称
适合简单项目（无复杂依赖、无额外资源文件），3 步即可完成。
打开命令行，切换到 Python 代码所在文件夹（示例路径）：
cd D:\PythonProjects\ImageTool # 替换为你的代码目录
核心命令格式：
pyinstaller [参数] 代码文件名.py
以 GUI 程序（无命令行窗口）为例，执行：
pyinstaller -F -w main.py
| 参数 | 作用 | 适用场景 |
|---|---|---|
-F/--onefile | 生成单个 EXE 文件（方便分发） | 小体积项目、快速分享 |
-w/--windowed | 隐藏命令行窗口（GUI 程序必加） | Tkinter/Qt 等 GUI 项目 |
-i/--icon | 设置 EXE 图标（格式为.ico） | 需要自定义图标时 |
--hidden-import | 手动添加未自动识别的依赖 | 依赖缺失时 |
打包完成后，项目目录会生成 3 个文件 / 文件夹：
dist 文件夹：存放最终的 EXE 文件（可直接双击运行，核心输出）build 文件夹：临时编译文件（无用，可删除）xxx.spec 文件：打包配置文件（后续优化打包用）针对复杂项目（如 GUI 程序、带资源文件、依赖缺失），需通过参数或配置文件优化。
PyInstaller 可能无法自动识别部分依赖（如 Pillow、自定义模块），导致运行 EXE 时提示'找不到模块'。
命令行添加 --hidden-import 参数，示例：
pyinstaller -F -w --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py
--hidden-import 可重复使用，添加所有未被识别的依赖模块。给 EXE 添加个性化图标（格式必须为.ico，推荐尺寸 256x256）。
-i 参数）：pyinstaller -F -w -i app.ico main.py # app.ico 替换为你的图标文件名
若项目引用了本地资源（如图标、配置文件），需在打包时指定资源路径，避免运行时找不到文件。
通过 -a 参数添加资源文件，格式：(源路径，目标路径)
pyinstaller -F -w --add-data "static;static" main.py
static;static 表示将本地 static 文件夹（含资源）打包到 EXE 同级的 static 文件夹中。后续'精细化打包'章节详细说明。
当命令行参数无法满足需求（如多资源文件、压缩优化、自定义输出路径）时，可通过修改自动生成的 xxx.spec 文件实现精细化配置。
执行基础打包命令后，会自动生成与代码文件同名的 .spec 文件（如 main.spec），也可手动创建：
pyinstaller -D main.py # -D 生成目录模式，仅用于生成 spec 文件
用记事本 / VS Code 打开 main.spec，核心配置如下（以 GUI 项目为例）：
# -*- mode: python ; coding: utf-8 -*-
block_cipher =None
# 1. 分析项目（依赖、资源文件）
a = Analysis(['main.py'],# 你的代码文件
pathex=[],# 项目路径（默认无需修改）
binaries=[],# 二进制文件（如.dll，默认空）
datas=[("static","static")],# 资源文件：(源路径，目标路径)
hiddenimports=['PIL.Image','PIL.ImageTk'],# 手动添加依赖
hookspath=[], excludes=[],# 排除无用模块（减小体积），如：'tkinter.tix'
cipher=block_cipher,)
# 2. 打包为 PYZ 文件（依赖压缩）
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
# 3. 配置 EXE 输出参数
exe = EXE(
pyz, a.scripts, a.binaries, a.zipfiles, a.datas,[], name='图片分类工具',# 自定义 EXE 文件名
debug=False, upx=True,# 启用 UPX 压缩（减小 EXE 体积）
upx_exclude=[], runtime_tmpdir=None, console=False,# 隐藏命令行窗口（等同于-w 参数）
icon='app.ico',# 图标路径（无图标可删除此行）)
修改完 spec 文件后，执行以下命令（注意：参数是 spec 文件，不是 py 文件）：
pyinstaller main.spec
-i 参数，使用系统默认图标；--hidden-import=模块名；hiddenimports 中添加模块（多个用逗号分隔）。-w 参数隐藏了命令行，无法查看错误；-w 参数重新打包，运行 EXE 时会弹出命令行，查看报错信息；upx=True，需提前安装 UPX：UPX 官网）；excludes 中排除无用模块（如 excludes=['unittest', 'tkinter.tix']）；numpy 等大体积依赖（必要时用虚拟环境隔离）。--add-data 参数指定资源路径；sys._MEIPASS 获取打包后的资源路径）。结合本文 GUI 项目（依赖 Pillow、需隐藏命令行、自定义图标），推荐命令：
pyinstaller -F -w -i app.ico --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py
pyinstaller -F -w --hidden-import=PIL.Image --hidden-import=PIL.ImageTk main.py
PyInstaller 是 Python 打包的首选工具，通过基础命令可快速生成 EXE，通过 spec 文件可实现精细化配置。打包核心要点：
-w 参数，避免命令行窗口；--hidden-import 补充；-w 参数查看报错信息。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online