第三讲：pyinstaller 核心概念全景图

2025-07-14

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

👉 本开源项目的交流群 👈

大家好，这里是程序员晚枫，全网同名。

（对应图中 3.1 → 3.4 的完整闭环）

开场 30 秒
“会敲 pyinstaller --onefile 只是开始；弄懂它背后做了什么，才能在别人问『为什么 50 MB、为什么闪退』时心里有底。”
本讲 10 分钟带你把 pyinstaller 的“黑盒”拆开。

3.1 打包流程总览（2 min）

一条命令背后 5 个阶段：

解析（Parse）
CLI 参数 → 内部配置。
分析依赖（Analysis）
AST 扫描 + 模块递归 → 生成文件清单。
生成 spec（Makespec）
把清单写成 Python 脚本 xxx.spec。
构建（Build）
运行 spec：拷贝字节码、收集二进制、加密/压缩。
生成 dist（Finalize）
输出 dist/ 目录或单文件 exe。

记忆口诀：Parse → Analyze → Spec → Build → Dist（PASBD）。

3.2 Bootloader 与运行时目录结构（3 min）

• Bootloader
一段 C 写的最小可执行程序，职责：

解压（或映射）运行时文件到临时目录
启动 Python 解释器
执行你的 __main__

• _MEIPASS
运行时临时目录路径，存放所有依赖。
代码里动态定位资源必须用它：

1
2
3

import sys, pathlib
base = pathlib.Path(sys._MEIPASS) if hasattr(sys, '_MEIPASS') else pathlib.Path('.')
logo = base / 'data' / 'logo.png'

• 目录结构对比

--onedir（默认）
dist/
└─ hello/
   ├─ hello.exe
   ├─ python311.dll
   ├─ _internal/
   │  ├─ lib/
   │  ├─ hello.exe.manifest
   │  └─ ...

--onefile
dist/hello.exe   # 单个文件，启动时解压到 %TEMP%\_MEIxxxx

3.3 单文件 vs 单目录：如何权衡（3 min）

维度	–onefile	–onedir
体积	多 5~10 MB（压缩开销）	略小
启动速度	慢（解压）	快
文件数量	1 个，易分发	多，易丢文件
防病毒误报	较高	较低
可就地更新	否（exe 占用）	是（替换 dll 即可）
场景	U 盘工具、在线下载	内部网络、游戏模组

一句话口诀：
“外发用单文件，内网用单目录；调试阶段先 --onedir 省时间。”

3.4 交叉打包的限制（2 min）

官方立场：

Windows → 只能打包 Windows
macOS → 只能打包 macOS
Linux → 只能打包 Linux

原因：
• 二进制扩展库（.pyd / .so）与系统 ABI 强绑定
• bootloader 预编译为各平台专用

变通方案：

用 CI（GitHub Actions）三系统并行打包
Docker 容器打包 Linux AppImage
虚拟机 + 共享文件夹

小结 & 下节预告（30 秒）

• 记住 PASBD 流程
• 用 _MEIPASS 定位资源
• 根据场景在单文件 / 单目录之间切换
• 交叉打包别硬刚，交给 CI

下节课《第四讲：命令行参数全解析》把常用开关一网打尽，让你 3 行命令完成 80 % 需求。