Python 编程实战 ：打包与发布（PyInstaller / pip 包发布）

在 Python 开发走向进阶和职业化的阶段，"把写好的代码交付出去"是无法绕开的能力。无论是给非技术人员提供可执行程序，还是将自己的项目发布到 PyPI，为全球开发者使用，掌握专业的打包与发布流程都是必须的。

本篇博客从零到一带你熟悉：

• PyInstaller：把 Python 项目打包成 EXE / APP
• pip 包发布流程：把你的项目推向 PyPI
• 常见坑与最佳实践

让你写的 Python 程序能真正"走出去"，触达更多真实用户。

---

一、使用 PyInstaller 打包可执行程序

1. PyInstaller 是什么？

PyInstaller 是将 Python 程序打包成可执行文件（如 Windows 的 .exe）的最常用工具。它会把 Python 解释器 + 所有依赖打包进一个独立文件，用户无需 Python 环境即可运行。

适合场景：

✔ 给用户分发桌面工具 ✔ 内部办公自动化脚本 ✔ GUI 程序（Tkinter、PyQt、wxPython 等） ✔ 命令行工具

---

2. PyInstaller 基本使用

安装：

pip install pyinstaller

最简单的打包：

pyinstaller main.py

完成后，目录结构如下：

dist/
    main/
        main.exe
build/
main.spec

最终可执行文件就在 dist 目录里。

---

3. 常用参数（必须掌握）

单文件打包

pyinstaller -F main.py

优点：只生成一个 .exe 缺点：启动稍慢

隐藏控制台窗口（GUI 程序）

pyinstaller -F -w main.py

加入图标

pyinstaller -F -i icon.ico main.py

添加数据文件（图片、配置、模型）

推荐在 .spec 文件中配置：

a = Analysis(
    ...,
    datas=[('config.yml', 'config.yml'), ('assets/', 'assets/')],
)

然后：

pyinstaller main.spec

---

4. 打包常见问题（超实用）

（1）打包后无法运行 / 缺少模块

原因：PyInstaller 未能自动识别依赖 解决：

pyinstaller -F main.py --hidden-import xx_module

---

（2）打包文件太大？

解决方式：

• 使用 UPX 压缩
• 删除 matplotlib/numpy 中用不到的 DLL

---

（3）Mac 打包的 app 无法在另一台 Mac 运行

因为 macOS 的签名安全机制，建议：

• 在目标版本系统构建（如 macOS 14）
• 结合 codesign --deep 进行签名

---

二、Python 包发布到 PyPI（pip install 可用）

让别人可以：

pip install yourpackage

这是专业 Python 开发者的重要能力之一。

---

1. 项目结构（最推荐）

myproject/
    myproject/
        __init__.py
        core.py
    tests/
    README.md
    pyproject.toml
    LICENSE

最关键：使用 pyproject.toml（现代标准）

---

2. 使用 build 进行构建

安装：

pip install build twine

构建：

python -m build

生成：

dist/
    myproject-1.0.0.tar.gz
    myproject-1.0.0-py3-none-any.whl

---

3. 发布到 TestPyPI

避免污染正式 PyPI。

twine upload --repository testpypi dist/*

安装测试版：

pip install -i https://test.pypi.org/simple/ myproject

---

4. 正式发布到 PyPI

twine upload dist/*

全世界的人就都可以：

pip install myproject

---

5. pyproject.toml 示例（最推荐）

下面是一个专业示例，可直接复用：

[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "1.0.0"
authors = [
    { name="Your Name", email="you@example.com" }
]
description = "A powerful and modern Python utility."
readme = "README.md"
license = { file="LICENSE" }
requires-python = ">=3.8"
dependencies = ["requests", "numpy"]

[project.urls]
Homepage = "https://github.com/you/myproject"
Documentation = "https://myproject-docs.com"

---

6. PyPI 发布常见问题

（1）403 权限错误

未创建 API Token 或 Token 配置错误 → 进入 pypi.org/manage/acco... 创建 Token 并更新 .pypirc

---

（2）版本号冲突

PyPI 版本号不能重复 → 每次发布前更新版本号（如：1.0.1 → 1.0.2）

---

（3）依赖未安装

确保 dependencies 正确写到 pyproject.toml

---

三、两者对比：应该用哪个？

场景	PyInstaller	PyPI 包发布
给普通用户（没 Python 环境）	✔ 最佳选择	✘
给开发者	✔	✔✔（最推荐）
分发 GUI 工具	✔	无意义
库 / SDK 发布	✘	✔最佳

---

四、最佳实践总结

✔ 办公/桌面工具 → PyInstaller

稳定、方便、用户无须 Python

✔ 开发者工具 → PyPI 发布

现代 Python 项目的标准做法

✔ 推荐结合 CI 自动化发布

GitHub Actions + PyPI + build 可以做到"打 tag 自动发布"

---