Python 项目开发完成后，如何优雅地发布和安装？传统的python setup.py install虽然可用，但不够现代化，也不方便在不同环境中快速分发。今天，我们就来详细讲解如何将 Python 源码打包成.whl文件（Wheel），并进行安装和分发。
一、为什么选择 .whl 文件
.whl是 Python 官方推荐的二进制分发格式，相比传统的源码安装有几个优势：
- 快速安装：不需要编译，直接
pip install xxx.whl - 跨平台（纯 Python）：如果没有 C 扩展，可以在不同操作系统间通用
- 规范标准：兼容现代 Python 打包工具，如
pip和build - 可控依赖：打包时可以指定依赖，安装时自动拉取
二、项目结构准备
假设你的项目名称是mypkg，最基础的目录结构如下：
mypkg/ ├── mypkg/ │ ├── __init__.py │ └── core.py ├── README.md ├── setup.py # 传统方式 └── pyproject.toml # 现代方式推荐
mypkg/：核心代码setup.py：兼容老项目的打包配置pyproject.toml：现代标准的打包配置
三、现代方式：pyproject.toml 打包
Python 官方推荐使用 PEP 517/518 标准，通过pyproject.toml来描述构建和依赖信息。
1. 安装打包工具
pip install build wheel setuptools
2. 配置pyproject.toml
[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] name = "mypkg" version = "0.1.0" description = "My Python Package" readme = "README.md" authors = [ { name="Your Name", email="you@example.com" } ] dependencies = [] [tool.setuptools.packages.find] where = ["."]
3. 构建.whl文件
在项目根目录执行：
python -m build
生成结果在dist/目录：
dist/ ├── mypkg-0.1.0-py3-none-any.whl └── mypkg-0.1.0.tar.gz
4. 本地安装测试
pip install dist/mypkg-0.1.0-py3-none-any.whl
四、传统方式：setup.py打包
对于老项目，如果还在用setup.py，也可以生成.whl：
# setup.py from setuptools import setup, find_packages setup( name="mypkg", version="0.1.0", packages=find_packages(), install_requires=[], )
构建：
python setup.py bdist_wheel
生成的.whl文件同样在dist/目录。
五、源码保护与加密（可选）
.whl文件本质上仍然包含源码，如果想防止直接查看 Python 代码，可以考虑：
方案 1：Cython 编译
.py → .pyx → .so / .pyd → 打包成 whl
适合核心逻辑不想暴露的商业项目。
方案 2：PyArmor 混淆
pip install pyarmor pyarmor gen mypkg/
可以对源码进行混淆，提高反编译成本。
六、总结
.whl是现代 Python 项目的推荐分发格式- 现代方式使用
pyproject.toml+build，简单快捷 - 传统方式
setup.py依然可用 - 可选混淆/编译策略保护核心源码
通过打包成.whl，你可以方便地分发、安装和管理 Python 项目，让用户体验更流畅，也方便 CI/CD 自动化部署。
