pyinstaller 打包实战教程大纲

👉 项目官网：https://www.python-office.com/ 👈

👉 本开源项目的交流群 👈

大家好，这里是程序员晚枫，正在all in AI编程实战，全网同名。

pyinstaller 打包实战教程大纲
（面向 Python 3.8+，Windows / macOS / Linux 全覆盖）

开篇：为什么学 pyinstaller
1.1 从「跑在开发机」到「交付给任何人」
1.2 常见打包方案的横向对比（pyinstaller vs cx_Freeze vs Nuitka vs Briefcase）
1.3 本教程阅读路径图（快速上手 → 深度定制 → 疑难杂症）
环境准备与初体验
2.1 安装 Python 与虚拟环境（venv / conda）
2.2 安装 pyinstaller 及版本选择（pip vs conda-forge）
2.3 30 秒打包 Hello World：一行命令生成可执行文件
2.4 第一次运行：常见报错速查表（PATH、防病毒误报等）
pyinstaller 核心概念
3.1 打包流程总览：解析 → 分析依赖 → 生成 spec → 构建 → 生成 dist
3.2 bootloader 与运行时目录结构（_MEIPASS）
3.3 单文件（--onefile）vs 单目录（--onedir）的权衡
3.4 交叉打包的限制（Windows 只能打包 Windows 等）
命令行参数全解析
4.1 常用开关：--name、--icon、--windowed、--noconfirm
4.2 隐藏导入（--hidden-import）与排除模块（--exclude-module）
4.3 数据文件与二进制文件捆绑：--add-data、--add-binary
4.4 UPX 压缩、数字签名、版本信息（--version-file）
.spec 文件深度定制
5.1 从命令行到 spec：pyi-makespec 的用法
5.2 Analysis、PYZ、EXE、COLLECT 四大对象拆解
5.3 多入口打包（多 CLI 工具合集）
5.4 为不同平台写条件分支（if sys.platform == "darwin"）
图形界面应用打包实战
6.1 Tkinter / PyQt5 / PySide6 的常见坑
6.2 处理 Qt 插件、图片格式 DLL
6.3 避免“双击无反应”：--windowed 与日志调试技巧
6.4 高 DPI 与暗黑模式适配
数据科学类项目专场
7.1 Numpy、Pandas、Scikit-learn 的体积优化
7.2 Torch / TensorFlow GPU 版本的裁剪策略
7.3 打包 Jupyter Notebook 为桌面应用（Voila + pyinstaller）
跨平台打包 CI/CD
8.1 GitHub Actions 三系统并发打包示例
8.2 上传 Release、自动生成 SHA256 校验文件
8.3 Docker 内打包 Linux AppImage 的可复现流程
运行时问题的定位与解决
9.1 查看解压目录：设置 --runtime-tmpdir
9.2 日志级别 --log-level DEBUG
9.3 常见错误代码对照表（Error loading Python DLL / Failed to execute script）
9.4 防病毒误报与代码签名最佳实践
进阶主题
10.1 自解压安装包（Inno Setup / NSIS / pkgbuild）
10.2 插件化架构：运行时动态加载外部 .py
10.3 使用 Nuitka 作为 pyinstaller 的“后端”加速启动
10.4 加密字节码（--key）与商业保护方案探讨
实战案例串讲
• CLI 工具：带自动更新（GitHub Release API）
• 游戏外挂：最小化体积（UPX + excludes）
• 数据可视化大屏：PyQtGraph + WebEngine
• 服务端脚本：打包为系统服务（systemd / Windows Service）
附录
A. 速查表：常用命令 & 典型 spec 模板
B. 社区资源：GitHub Issues 高频问题、Reddit 讨论帖
C. 版本升级迁移笔记（4.x → 5.x → 6.x 破坏性变更）
D. 贡献代码：如何给 pyinstaller 提 Pull Request