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 自動化部署。
