第十二讲：附录 & 社区资源 ——速查表、模板仓库、贡献指南与版本迁移笔记

2025-07-14

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

（本讲可永久收藏，随查随用）

12.1 一页纸速查表（A4 横向打印版）

目标	命令 / 片段	备注
最常用打包	`pyinstaller --onefile --name app --icon app.ico main.py`	90 % 场景
GUI 无黑框	`--noconsole` (Win) / `--windowed` (mac)	与 `console=False` 等价
数据文件	`--add-data "src/data;data"` (Win) `--add-data "src/data:data"` (Unix)	分隔符不同
隐藏导入	`--hidden-import pkg.sub`	动态 import 必备
排除模块	`--exclude-module matplotlib.tests`	瘦身首选
UPX 压缩	`--upx-dir /usr/local/bin --upx-exclude Qt5Core.dll`	需先装 UPX
版本信息	`--version-file version.txt`	Win 专属
调试	`--onedir --debug all`	本地复现首选
服务打包	`--onedir` + systemd / sc	第十二讲项目 3
交叉打包	不能！用 CI 多 job	记住即可

12.2 官方 & 社区资源

类型	链接	用途
官方文档	https://pyinstaller.org/en/stable/	权威 API & hook 列表
GitHub Issues	https://github.com/pyinstaller/pyinstaller/issues	搜关键字 + label:bug
Discussions	https://github.com/pyinstaller/pyinstaller/discussions	提问前先搜
中文论坛	https://discuss.python.org/c/packaging	中文交流
Hook 仓库	https://github.com/pyinstaller/hooks	提交自定义 hook
速查卡片	本讲 12.1	打印贴屏幕

12.3 模板仓库（直接 fork）

GitHub：github.com/yourname/pyinstaller-templates
目录结构：

templates/
├─ cli-auto-update/        # 第十一讲项目 1
├─ qt-gui-installer/       # 第十一讲项目 2
├─ ml-service/             # 第十一讲项目 3
├─ minimal.spec            # 最小可改模板
├─ cross-ci.yml            # GitHub Actions 通用
└─ version_info.txt        # Windows 版本信息样例

使用：
git clone → 改名字 → 替换图标 → Push tag → 5 分钟出 Release。

12.4 版本迁移笔记（4.x → 5.x → 6.x）

版本	破坏性变更	迁移动作
4.10 → 5.0	`--onedir` 目录结构改变	把脚本里硬编码 `dist/app/_internal` 改为 `sys._MEIPASS`
5.x → 6.0	UPX 默认关闭	如需压缩手动 `--upx-dir`
6.x → 7.0 (预览)	移除 Python 3.7 支持	升级到 3.8+

官方迁移指南：
https://pyinstaller.org/en/stable/CHANGES.html

12.5 如何给 pyinstaller 贡献代码（2 min）

Fork → 新建分支 fix-hook-torch
修改 pyinstaller/hooks/hook-torch.py

运行测试

1 2	pip install -e ".[testing]" pytest tests/functional/test_hooks/test_torch.py -v

提交 PR → 等待 review → 合并后你的名字出现在下一版 release notes！

12.6 常见“一句话”备忘录

• 体积爆炸 → 先 --onedir 看哪个文件最大
• 闪退无日志 → 发 --console 诊断版
• macOS “已损坏” → xattr -dr com.apple.quarantine MyApp.app
• Win 报毒 → 关闭 UPX + 代码签名
• 插件不加载 → 打印 sys.path 检查 _MEIPASS 外路径

结课彩蛋

你已走完 12 讲：
CLI → GUI → ML → CI/CD → 安装包 → 插件化 → 商业保护 → 社区贡献。

下一步：

把本讲速查表贴在工位
fork 模板仓库，发你的第一个 Release
遇到新问题，回到 12.2 的链接提问或提 PR

祝打包愉快，永不踩坑！

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