188 lines
4.6 KiB
Markdown
188 lines
4.6 KiB
Markdown
# 🚀 Python 包发布到 PyPI 完整指南
|
||
|
||
## 📋 快速开始 (一键复现)
|
||
|
||
### 🚀 使用 Makefile (推荐)
|
||
```bash
|
||
make help # 查看所有命令
|
||
make install # 安装开发环境
|
||
make clean # 清理构建文件
|
||
make build # 构建包
|
||
make check # 检查包格式
|
||
make publish # 发布到 PyPI
|
||
make all # 运行所有检查和构建
|
||
```
|
||
|
||
### 🔧 使用脚本
|
||
```bash
|
||
# 交互式发布 (推荐)
|
||
python publish.py
|
||
|
||
# 自动发布到 PyPI (无交互)
|
||
python publish.py --auto
|
||
|
||
# 发布到 TestPyPI
|
||
python publish.py --test
|
||
|
||
# 仅构建和检查，不发布
|
||
python publish.py --check-only
|
||
```
|
||
|
||
### ⚡ 手动命令
|
||
```bash
|
||
# 环境准备
|
||
UV_PYTHON=python3.12 uv venv .venv
|
||
source .venv/bin/activate
|
||
uv pip install -e ".[dev]"
|
||
|
||
# 构建发布
|
||
rm -rf dist/ build/ *.egg-info/ src/*.egg-info/
|
||
python -m build
|
||
python -m twine check dist/*
|
||
python -m twine upload dist/*
|
||
```
|
||
|
||
## 📁 项目结构
|
||
```
|
||
project-name/
|
||
├── pyproject.toml # ⭐ 核心配置文件
|
||
├── README.md # 📖 项目文档
|
||
├── LICENSE # 📄 许可证文件
|
||
├── Makefile # 🔧 开发工具
|
||
├── publish.py # 🚀 发布脚本
|
||
├── src/
|
||
│ └── package_name/
|
||
│ ├── __init__.py # 包初始化
|
||
│ └── module.py # 核心模块
|
||
├── tests/
|
||
│ └── test_module.py # 测试文件
|
||
└── examples/
|
||
└── basic_usage.py # 使用示例
|
||
```
|
||
|
||
### ✅ 2. pyproject.toml 配置模板
|
||
|
||
```toml
|
||
[project]
|
||
name = "your-package-name"
|
||
version = "0.1.0"
|
||
description = "Your package description"
|
||
readme = "README.md"
|
||
authors = [
|
||
{ name = "Your Name", email = "your.email@example.com" }
|
||
]
|
||
requires-python = ">=3.9"
|
||
dependencies = [
|
||
"dependency>=1.0.0",
|
||
]
|
||
keywords = ["keyword1", "keyword2"]
|
||
classifiers = [
|
||
"Development Status :: 4 - Beta",
|
||
"Intended Audience :: Developers",
|
||
"Programming Language :: Python :: 3",
|
||
"Programming Language :: Python :: 3.9",
|
||
"Programming Language :: Python :: 3.10",
|
||
"Programming Language :: Python :: 3.11",
|
||
"Programming Language :: Python :: 3.12",
|
||
"Programming Language :: Python :: 3.13",
|
||
"Topic :: Software Development :: Libraries :: Python Modules",
|
||
]
|
||
|
||
[project.urls]
|
||
Homepage = "https://github.com/username/repo"
|
||
Repository = "https://github.com/username/repo"
|
||
Documentation = "https://github.com/username/repo#readme"
|
||
Issues = "https://github.com/username/repo/issues"
|
||
|
||
[project.optional-dependencies]
|
||
dev = [
|
||
# 测试工具
|
||
"pytest>=7.0.0",
|
||
"pytest-cov>=4.0.0",
|
||
|
||
# 代码格式化
|
||
"black>=23.0.0",
|
||
"isort>=5.12.0",
|
||
|
||
# 代码检查
|
||
"flake8>=6.0.0",
|
||
"mypy>=1.0.0",
|
||
|
||
# 打包工具 (仅开发环境需要)
|
||
"build>=1.0.0",
|
||
"twine>=4.0.0",
|
||
"setuptools>=68.0.0",
|
||
"wheel>=0.40.0",
|
||
]
|
||
|
||
[build-system]
|
||
requires = ["setuptools>=68.0.0", "wheel>=0.40.0"]
|
||
build-backend = "setuptools.build_meta"
|
||
```
|
||
|
||
## 🔧 PyPI 认证配置
|
||
|
||
创建 `~/.pypirc` 文件：
|
||
```ini
|
||
[distutils]
|
||
index-servers = pypi
|
||
|
||
[pypi]
|
||
username = __token__
|
||
password = pypi-your-api-token-here
|
||
```
|
||
|
||
## ⚠️ 避免常见陷阱
|
||
|
||
1. **❌ 不要创建 build.py 文件** - 会与 `python -m build` 冲突
|
||
2. **❌ 不要手动编辑许可证字段** - 使用 classifiers
|
||
3. **❌ 不要混合开发和运行时依赖** - 打包工具放在 dev 依赖中
|
||
4. **✅ 使用现代构建系统** - PEP 517/518 标准
|
||
|
||
## 🚨 故障排除
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|----------|
|
||
| build.py 冲突 | 重命名或删除项目中的 build.py |
|
||
| 许可证元数据错误 | 移除 pyproject.toml 中的 license 字段 |
|
||
| 包名冲突 | 在 PyPI 搜索确认包名可用性 |
|
||
| 依赖解析失败 | 检查版本约束和兼容性 |
|
||
|
||
## ✅ 发布检查清单
|
||
|
||
- [ ] pyproject.toml 配置完整
|
||
- [ ] README.md 文档详细
|
||
- [ ] LICENSE 文件存在
|
||
- [ ] 测试通过
|
||
- [ ] `twine check` 通过
|
||
- [ ] 版本号正确
|
||
- [ ] PyPI 认证配置
|
||
|
||
## 🎯 版本兼容性
|
||
|
||
- **Python 版本**: 3.9-3.13
|
||
- **Wheel 标签**: `py3-none-any` (通用兼容)
|
||
- **构建系统**: setuptools (稳定可靠)
|
||
|
||
## 📝 最佳实践
|
||
|
||
1. **版本管理**: 使用语义化版本 (SemVer)
|
||
2. **文档**: 提供完整的 README.md 和使用示例
|
||
3. **测试**: 包含完整的测试套件
|
||
4. **CI/CD**: 设置自动化测试和发布流程
|
||
5. **安全**: 使用 API token 而不是用户名密码
|
||
|
||
## <20> 发布后验证
|
||
|
||
```bash
|
||
# 安装验证
|
||
pip install your-package-name
|
||
|
||
# 功能验证
|
||
python -c "import your_package; print('✅ 安装成功')"
|
||
```
|
||
|
||
---
|
||
|
||
**这个指南确保每次都能成功发布到 PyPI！** 🚀
|