Python项目发布流程自动化核心是统一用pyproject.toml管理配置，结合setuptools-scm自动推导语义化版本，通过CI分阶段验证（lint/test/build/publish）并联动更新文档与CHANGELOG，确保每次发布可控、可溯、一致。
Python项目发布流程自动化，核心是把“写完代码→测试通过→打标签→构建包→上传PyPI→更新文档”这一串手动操作变成可重复、可验证、可回溯的稳定动作。关键不在工具多炫，而在每一步是否可控、失败能否快速定位、版本是否严格一致。
用pyproject.toml统一配置，告别setup.py和setup.cfg分裂
现代Python发布强烈推荐只用pyproject.toml一个文件管理构建系统、依赖、元数据和发布配置。它替代了过去setup.py（执行逻辑混乱）、setup.cfg（纯配置但不支持动态行为）、requirements.txt（与构建脱节）三者混用的问题。
示例关键段落：
- 构建系统声明：明确指定build-backend为setuptools或hatchling，避免pip自动选择导致行为不一致
- 项目元数据：name、version、description等直接写死或通过动态方式（如importlib.metadata读取__version__）注入，确保源码中版本与包内版本严格一致
- 发布相关配置：比如[project.optional-dependencies]定义dev/test环境，[build-system]指定依赖，避免本地构建成功但CI失败
版本号管理必须自动化，禁止手改__version__
人工修改字符串容易出错：提交了代码却忘了改版本、打了tag但包里还是旧版、预发布版本（如0.5.0a1）误发成正式版。可靠做法是采用语义化版本+自动化推导。
立即学习“Python免费学习笔记（深入）”；
- 使用setuptools-scm：从Git tag自动计算版本（如v0.4.2 → 0.4.2；v0.4.2-3-gabc123 → 0.4.2.dev3+gabc123），无需维护__version__.py
- 发布前只做一件事：git tag -a v0.5.0 -m "release 0.5.0" && git push --tags；后续所有构建都基于此tag生成确定版本
- CI中校验：检查当前commit是否已打tag，未打则拒绝构建发布包，防止误发
CI流水线分阶段验证，每个环节失败即止
GitHub Actions / GitLab CI 不是“跑完脚本就完事”，而是按可信度递进设计阶段：
- lint & type check：pre-commit + mypy，语法和类型错误在最前端拦截
- test：pytest + coverage，覆盖单元/集成测试，覆盖率低于阈值（如80%）可设为警告但不阻断
- build：poetry build 或 python -m build，验证能正常生成sdist/wheel，且wheel内容符合预期（如无.pyc、无.git目录）
- publish：仅当PR合并到main、且commit带v* tag时触发；使用API token上传至test.pypi.org先验，确认无误再推正式PyPI
发布后自动同步，减少人为遗漏
发完包不等于结束。用户看到的文档、CHANGELOG、README中的版本号、甚至下游依赖的兼容声明，都应随发布动作联动更新。
- 用towncrier或changeset生成CHANGELOG：每次PR带碎片化变更描述，发布时自动聚合为结构化日志
- 用doctr或mkdocs gh-deploy自动部署文档站点，绑定同一tag，确保文档与对应版本代码完全匹配
- 在PyPI页面展示的README.md，建议用twine check验证渲染效果，避免rst/md语法错误导致描述空白
不复杂但容易忽略。自动化不是为炫技，是让每次发布都像拧一颗标准螺丝——力矩、深度、材质全部受控。真正可靠的发布，是没人盯着也能稳稳落地。
