从零到上线：Python开源项目的规范化开发与发布指南

从零到上线：Python开源项目的规范化开发与发布指南

• 旨在为准备发布并维护自己的项目的小伙伴提供一份完整的操作指南

一、创建阶段：项目脚手架搭建

1.1 虚拟环境的搭建与隔离

• 一个良好的项目从隔离的运行环境开始，便于后续的发布和他人部署
• 使用pyenv管理Python版本与虚拟环境

mkdir my-project
cd my-project
# 创建虚拟环境并激活
pyenv virtualenv 3.11.0 my-project
pyenv local my-project
# 验证环境
python –version
which python

💡 为什么用 pyenv 而不是 venv？ pyenv 支持多版本切换，适合同时维护多个项目；pyenv local 会生成 .python-version 文件，进入目录时自动激活对应环境。

1.2 Git初始化与.gitignore 配置

• 配置忽略文件来保护如api_key之类的敏感信息

git init

cat > .gitignore << EOF
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
*.egg

# 环境与密钥
.env
.venv/
*.pem
*.key

# IDE
.vscode/
.idea/
*.iml

# 系统文件
.DS_Store
Thumbs.db
EOF

💡 也可以使用 gitignore.io 按技术栈自动生成。

1.3 环境变量配置

cat > .env << EOF
# 数据库配置
DATABASE_URL=******
# API Key
LLM_API_KEY=******
EOF
echo ".env" >> .gitignore

• 同时创建.env.example作为模版文件提交到你的Github仓库

cp .env .env.example

1.4 README 文件

• 一个规范的README应该包括: 项目介绍、功能特性、快速开始、安装说明、使用示例、贡献指南等

# My Project

> 一句话描述你的项目

## ✨ 特性
– 特性一
– 特性二

## 🚀 快速开始

pip install my-project

## 📖 使用示例
…

## 📄 许可证
MIT License

1.5 依赖管理

• requirements.txt 适合轻量级场景

pip freeze > requirements.txt

# requirements.txt（生产）
fastapi>=0.100.0
pydantic>=2.0.0

# requirements-dev.txt（开发）
pytest>=7.0.0
black>=23.0.0
ruff>=0.1.0

1.6 项目配置文件

• 现代Python项目推荐使用 pyproject.toml统一管理构建与工具配置
• 一个完整的TOML配置文件应该包含如下：

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"

[project]
name = "my-project"
version = "0.1.0"
description = "项目描述"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [{ name = "Your Name", email = "you@example.com" }]
dependencies = [
"fastapi>=0.100.0",
]

[project.urls]
Homepage = "https://github.com/yourname/my-project"

[tool.ruff]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

二、开发阶段：协作流程规范

2.1 Git 分支模型

• Git 分支模型带来的好处有：并行开发，版本管理、隔离风险等，是现在最常用的多人协作开发模型
• 主要的分支策略有两种：Git Flow、Github Flow
• Github Flow：feature/xxx -> develop -> main

### 关联远程仓库(你的github项目仓库)
git remote add origin https://github.com/yourname/my-project.git
### 指定为主分支
git branch -M main
### 推送分支
git push -u origin main

### 创建 develop 分支
git checkout -b develop
git push -u origin develop
### 开发新功能，切出其他分支
git checkout -b feature/add-login develop
### 开发完成后
git push origin feature/add-login

• 在Github上发起 PR，也称提PR

2.2 分支保护规则

• 在Github的Settings → Branches → Branch protection rules 对main分支设置

2.3 CI/CD 自动化

• 全称为**持续集成 **/ 持续交付
• CI主要为自动化测试和构建，开发者每次提交代码都会自动触发：单元测试、集成测试、代码风格检查、打包构建等
• CD主要为自动化部署到类生产环境，运行更深层次的测试：性能测试、安全扫描等
• 一般来说PR合并前CI必须通过，防止问题代码进入主干

2.4 PR 规范

• PR包括每次commit的标题建议遵循 Conventional Commits 格式：

feat: 添加用户登录功能
fix: 修复 token 过期未刷新问题
docs: 更新 API 文档
refactor: 重构数据库连接池逻辑

三、发布阶段：版本管理与PyPI上传

3.1 语义话版本号

• 通俗来讲就是如何命名每次发布的版本，格式为MAJOR.MINOR.PATCH

3.2 发布流程

# 1. 确保main分支代码最新
git checkout main
git pull origin main

# 2. 打 Tag
git tag v0.1.1
git push origin v0.1.1

# 3. 构建分发包
rm -rf dist/ build/
python -m build
# 会生成 dist/my_project-0.1.1.tar.gz 和 .whl 文件

# 4. 上传到 PyPI
twine upload dist/*
# 首次需要配置API Token(需two factors验证)

3.3 发布信息维护

• 每次发布前需要更新CHANGELOG.md，记录版本变更：

## [v0.1.1] – 2025-02-25
### Fixed
– 修复并发请求下的竞态条件问题

## [v0.1.0] – 2025-01-10
### Added
– 初始版本发布
– 支持基本的 CRUD 操作

• 或者在Releases界面直接编辑:

四、维护阶段：长期运维建议

• Issue模版：在.github/ISSUE_TEMPLATE/下配置 Bug Report和Feature Request模版、规范用户反馈。
• 依赖更新：定期执行 pip list –outdated 或接入 Dependabot 自动检测依赖安全漏洞。
• 文档站：使用 MkDocs + GitHub Pages 搭建在线文档，与代码仓库联动自动部署。