第五讲：.spec 文件深度定制

2025-07-14

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

（让 CLI 参数“退休”，进入 Python 脚本级打包）

开场 15 秒
CLI 参数再多也有天花板；真正做产品级打包，90 % 时间都在改 .spec。
本讲 15 分钟，把自动生成的 .spec 拆成 4 大对象，手把手改成“可维护、可扩展、可 CI/CD”的生产脚本。

5.0 回顾：从 CLI 到 spec 的两条路径

先 CLI 后 spec（推荐新手）

1 2	pyi-makespec --onefile --name MyApp --icon app.ico main.py # 得到 MyApp.spec，接着手工改

直接手写 spec（老司机）
复制模板 → 按业务填参数 → 一次到位。

5.1 四大对象全景图（3 min）

对象	作用	常改字段
Analysis	依赖扫描与收集	`scripts`, `pathex`, `datas`, `binaries`, `hiddenimports`, `excludes`
PYZ	压缩字节码 archive	一般不动
EXE	最终可执行文件	`name`, `icon`, `console`, `upx`, `version`
COLLECT	仅 `--onedir` 时用到，决定输出目录结构	很少改

5.2 最小可改模板（2 min）

# -*- mode: python ; coding: utf-8 -*-
import pathlib
SRC = pathlib.Path('.').resolve()

a = Analysis(
    ['src/main.py'],                     # 入口
    pathex=[SRC/'src', SRC/'lib'],       # 额外 import 路径
    binaries=[],                         # 手动 DLL/SO
    datas=[                              # 资源文件
        (SRC/'assets/logo.png', 'assets'),
        (SRC/'assets/config.json', '.'),
    ],
    hiddenimports=['pkg.sub'],           # 动态 import
    excludes=['matplotlib.tests', 'tkinter'],  # 瘦身
    hookspath=[],
    runtime_hooks=['hooks/rth_persists.py'],   # 运行时钩子
    cipher=None,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=None)

exe = EXE(
    pyz, a.scripts, a.binaries, a.zipfiles, a.datas,
    name='MyApp',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=['vcruntime140.dll'],
    runtime_tmpdir=None,
    console=False,            # GUI 程序
    icon=SRC/'assets/app.ico',
    version=SRC/'version.txt',
)

# 如果是 onedir，需要 COLLECT（本例 onedir 可省）
# coll = COLLECT(exe, ...)

5.3 高频场景 4 连击（每例 2 min）

① 多入口命令行工具
把 3 个脚本打成 3 个 exe：

entries = ['cli_a.py', 'cli_b.py', 'gui_c.py']
for e in entries:
    a = Analysis([f'src/{e}'], ...)
    exe = EXE(..., name=e.replace('.py', ''))

② 不同平台差异化构建

import sys
if sys.platform == 'darwin':
    exe = EXE(..., icon=SRC/'assets/app.icns')
elif sys.platform == 'win32':
    exe = EXE(..., icon=SRC/'assets/app.ico', version='version.txt')

③ 插件化：运行时加载外部 .pyd/.so

1	binaries=[(SRC/'plugins/*.pyd', 'plugins')]

运行时钩子 rth_persists.py 把 plugins/ 加入 sys.path。

④ 加密字节码（轻度防窥）

1 2	from PyInstaller.building.api import PYZ pyz = PYZ(a.pure, a.zipped_data, cipher='mykey')

⚠️ 仅轻度混淆，商业级仍需加壳。

5.4 与 CI/CD 结合（2 min）

GitHub Actions 片段

- name: Build with spec
  run: |
    pip install pyinstaller
    pyinstaller MyApp.spec

好处：

版本号、图标统一维护在 spec，不污染 workflow。
同一 spec 可在矩阵里跑 windows-latest、macos-latest、ubuntu-latest。

5.5 常见踩坑 & 调试技巧（2 min）

症状	排查命令	解决
资源路径找不到	打印 `sys._MEIPASS`	统一用 `pathlib.Path(sys._MEIPASS) / 'relative'`
spec 里变量不生效	`pyinstaller --log-level DEBUG MyApp.spec`	看 Analysis 日志
UPX 压坏 Qt DLL	`--upx-exclude "Qt5*.dll"`	黑名单

小结 & 下节预告（15 秒）

• 记住四大对象：Analysis → PYZ → EXE → COLLECT
• 把 CLI 参数“翻译”成 Python 变量，可读可维护
• spec 就是打包项目的 Makefile，后续瘦身、签名、加密都在此一层层加料

下节课《第六讲：图形界面应用打包实战（Tkinter / PyQt5 / PySide6）》让窗口程序真正“像一款软件”。

大家在学习课程中有任何问题，欢迎+微信和我交流👉我的联系方式：微信、读者群、1对1、福利