日常开发中，写好的Python脚本想分享给同事或客户，对方却没有Python环境？或者担心源码泄露？用PyInstaller把脚本打包成可执行文件，这些问题都能解决。作为Python生态中最流行的打包工具，PyInstaller最新版本6.14.2（2025年7月发布）带来了更稳定的兼容性和更强的安全性，支持Python 3.8到3.13版本（避开3.10.0和3.14 beta版）。今天就手把手教你从基础打包到高级配置，让你的脚本轻松变成可分发的exe文件。

一、准备工作：环境配置与安装

打包前先确认Python环境，推荐使用3.11或3.12版本（兼容性最佳）。打开命令提示符（Win+R输入cmd），输入python --version检查版本，没问题的话直接安装PyInstaller：

pip install pyinstaller

如果需要升级到最新版，加个-U参数：pip install -U pyinstaller。安装过程会自动处理依赖，包括pyinstaller-hooks-contrib（2025.8版本已支持uuid6、shapely等新库）。

注意：2025年起，PyInstaller禁止在C:\Windows目录下打包，也不建议用管理员权限运行（v7.0将彻底阻止），普通用户目录操作即可。

二、基础打包：3行命令搞定单文件/多文件

1. 单文件打包（最常用）

如果你的脚本是单个.py文件（比如main.py），用-F参数生成独立exe：

pyinstaller -F main.py

执行后会生成dist和build两个文件夹，build是临时文件可删除，dist里的main.exe就是最终产物，双击就能运行，无需Python环境。

2. 多文件/复杂项目打包

如果脚本依赖多个.py文件或文件夹，用-D参数（默认选项）生成文件夹形式的打包结果：

pyinstaller -D main.py

此时dist/main文件夹里会有main.exe和一堆依赖文件，适合项目结构复杂的情况。

小技巧：用-n参数自定义exe名称，比如pyinstaller -F -n "我的工具" main.py，生成的就是“我的工具.exe”。

三、高级配置：让你的exe更专业

1. 自定义图标

默认exe是系统图标，用-i参数换个好看的图标（需.ico格式）：

pyinstaller -F -i logo.ico main.py

图标尺寸推荐256x256像素，网上有免费的ico转换工具（如Convertio）。

2. 隐藏控制台窗口

GUI程序（如PyQt、Tkinter）运行时不需要黑框控制台，加-w参数隐藏：

pyinstaller -F -w -i logo.ico main.py

如果是命令行工具，不要加-w，否则用户看不到输出。

3. 处理数据文件（图片、配置等）

脚本中用到的图片、配置文件等，需要用datas参数告诉PyInstaller打包。比如assets文件夹下的图片，先通过pyi-makespec生成spec文件：

pyi-makespec main.py

然后编辑main.spec，修改datas：

a = Analysis(
    ['main.py'],
    datas=[('assets/*', 'assets')],  # 源路径:目标路径
    ...
)

最后用spec文件打包：pyinstaller main.spec。

4. 解决“模块找不到”问题

打包时经常遇到ModuleNotFoundError，比如缺少requests库。原因是PyInstaller没检测到动态导入的模块，两种解决办法：
- 命令行加--hidden-import：pyinstaller -F --hidden-import=requests main.py
- 编辑spec文件，在hiddenimports里添加：hiddenimports=['requests', 'numpy']

四、常见问题实战解决

1. 打包后exe太大？

用UPX压缩！先下载UPX（upx.github.io），解压后在打包命令中指定路径：

pyinstaller -F --upx-dir "C:\upx" main.py

能减小30%-50%体积，对图片、视频等资源无效。

2. 运行exe提示“缺少dll”？

Windows系统可能缺少vcruntime140.dll，这是Visual C++运行库，让用户安装“微软常用运行库合集”即可，或打包时用--collect-all参数强制收集：

pyinstaller -F --collect-all=your_module main.py

3. PyWebIO/Pyecharts等特殊库打包

以PyWebIO为例（CSDN博客2025年7月案例），需要修改spec文件处理递归深度和资源：

import sys
sys.setrecursionlimit(5000)  # 解决递归深度不足
from pywebio.utils import pyinstaller_datas

a = Analysis(
    ['app.py'],
    datas=pyinstaller_datas(),  # 自动收集PyWebIO资源
    hiddenimports=['aiohttp', 'jinja2'],
    ...
)

打包后把pyecharts文件夹手动复制到dist/app目录（避免静态资源缺失）。

五、避坑指南（2025最新版）

1. Python版本：支持3.8-3.13，避开3.10.0（有bug）和3.14 beta
2. 路径问题：脚本中用os.path获取路径时，打包后需用sys._MEIPASS获取临时目录，比如：import sys, os def get_resource(path): if hasattr(sys, '_MEIPASS'): return os.path.join(sys._MEIPASS, path) return os.path.join(os.path.abspath('.'), path)
3. 缓存清理：打包失败时用--clean参数清除缓存：pyinstaller --clean main.py

现在你已经掌握了PyInstaller的核心用法，从基础打包到解决复杂问题都没问题。动手试试把自己的脚本打包成exe，分享给朋友吧！如果遇到其他问题，PyInstaller官方文档（pyinstaller.org）和GitHub Issues有详细解答。