👉 项目官网：https://www.python-office.com/ 👈
👉 本开源项目的交流群 👈
大家好，这里是程序员晚枫，全网同名。
（对应“常用开关、隐藏导入、资源捆绑、UPX、版本信息”一次讲透）
开场 30 秒
“CLI 参数记不住？一行命令就能完成 80 % 场景，但前提是你知道哪些开关该拧哪颗螺丝。”
本讲 15 分钟，把最常用的 12 个参数做成「速查卡」，随抄随用。
4.0 速查表（先收藏，再细读）
| 目标 | 关键开关 | 示例 | 备注 |
|---|---|---|---|
| 单文件 | --onefile |
pyinstaller --onefile main.py |
启动稍慢 |
| 单目录 | --onedir |
默认 | 调试阶段更快 |
| 改名 | --name |
--name MyTool |
生成的 exe / 文件夹名 |
| 无黑框 | --noconsole / --windowed |
GUI 程序必加 | Win 用 --noconsole，macOS 用 --windowed |
| 图标 | --icon |
--icon=app.ico |
Win: .ico, macOS: .icns |
| 数据文件 | --add-data |
--add-data "data;data" |
Win 用 ;，Linux/Mac 用 : |
| 二进制文件 | --add-binary |
--add-binary "driver/*.dll;." |
同上 |
| 隐藏导入 | --hidden-import |
--hidden-import pkg.sub |
解决动态 import 报错 |
| 排除模块 | --exclude-module |
--exclude-module matplotlib |
瘦身利器 |
| UPX 压缩 | --upx-dir / --upx-exclude |
--upx-dir /usr/local/bin |
需先装 UPX |
| 版本信息 | --version-file |
--version-file version.txt |
Win 专用 |
| 强制覆盖 | --noconfirm |
不弹出 “是否删除 build” | CI/CD 常用 |
4.1 最小可行组合（90 % 场景）
1 | pyinstaller --onefile --name MyTool --icon app.ico --add-data "data;data" main.py |
解释：
- 单文件、改名字、加图标、顺带把
data/文件夹一起打包。
4.2 隐藏导入与排除模块（2 min）
现象：运行时报 ModuleNotFoundError: No module named 'xyz'，但本地能跑。
原因：PyInstaller 的静态分析找不到 __import__ / importlib 动态加载的模块。
解决：
1 | pyinstaller main.py --hidden-import xyz --hidden-import abc.def |
瘦身反面案例：
1 | pyinstaller main.py --exclude-module matplotlib --exclude-module PyQt5 |
4.3 UPX 压缩实战（2 min）
安装
- Windows：下载 upx.exe 放到 PATH
- macOS：
brew install upx - Linux：
apt install upx
打包
1
pyinstaller --onefile --upx-dir /usr/local/bin --upx-exclude "vcruntime140.dll" main.py
经验：
- DLL/某些 PyQt 插件被 UPX 压坏时，用
--upx-exclude黑名单跳过。 - 体积一般再减 30 % ~ 50 %。
4.4 版本信息一站式生成（Windows，2 min）
官方模板太长？用 pyinstaller-versionfile 一键生成：
1 | pip install pyinstaller-versionfile |
然后：
1 | pyinstaller --onefile --version-file version.txt main.py |
右键 exe → 属性 → 详细信息，版本号、公司名、版权全部就位。
4.5 一条命令太长？转 .spec 继续拧螺丝（1 min）
1 | pyi-makespec --onefile --name MyTool --icon app.ico --add-data "data;data" main.py |
生成 MyTool.spec 后，想再改 UPX、隐藏导入，直接改 spec，再：
1 | pyinstaller MyTool.spec |
小结 & 下节预告（30 秒）
• 记牢 12 个高频开关，90 % 场景够用
• 动态 import 报错 → --hidden-import
• 瘦身三板斧：--exclude-module、--upx-dir、--exclude-module
下节课《第五讲：.spec 文件深度定制》带你把 CLI 参数“翻译”成可读可改的 Python 脚本，开启高级玩法。
大家在学习课程中有任何问题，欢迎+微信和我交流👉我的联系方式：微信、读者群、1对1、福利
