发布python包到pypi需三步：整理规范包结构（推荐pyproject.toml）、构建分发包（python -m build）、上传至pypi（twine upload），关键在元数据准确、打包干净、认证正确。
把 Python 包发布到 PyPI，核心是三步：准备包结构、构建分发包、上传到 PyPI。关键不在代码多复杂，而在元数据是否规范、打包是否干净、认证是否正确。
一、整理包结构，确保符合 PyPI 要求
PyPI 不接受任意目录结构。推荐标准布局如下：
-
my_package/ —— 源码包（含
__init__.py） - setup.py 或 pyproject.toml（推荐后者，现代标准）
- README.md（必须，首页展示）
- LICENSE（建议包含）
-
requirements.txt（可选，开发依赖建议放
pyproject.toml中）
特别注意：setup.py 已逐步被弃用；Python 3.12+ 官方只推荐使用 pyproject.toml 配合 setuptools 或 hatch 等构建后端。
二、编写 pyproject.toml，声明元信息和依赖
这是当前最稳妥的方式。一个最小可用示例：
立即学习“Python免费学习笔记（深入）”；
[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"
<p>[project]
name = "my-package"
version = "0.1.0"
description = "A short description"
readme = "README.md"
authors = [{name = "Your Name", email = "you@example.com"}]
license = {text = "MIT"}
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
]
requires-python = ">=3.8"
dependencies = [
"requests>=2.25.0",
]</p><p>[project.urls]
Homepage = "<a href="https://www.php.cn/link/ce4ef2a93a49e822821eb2038540a6d3">https://www.php.cn/link/ce4ef2a93a49e822821eb2038540a6d3</a>"
Repository = "<a href="https://www.php.cn/link/ce4ef2a93a49e822821eb2038540a6d3">https://www.php.cn/link/ce4ef2a93a49e822821eb2038540a6d3</a>"
版本号建议遵循 Semantic Versioning；requires-python 明确指定支持的 Python 版本范围，避免用户安装失败。
三、构建并本地验证分发包
在项目根目录运行：
python -m build
会生成 dist/my_package-0.1.0-py3-none-any.whl 和 dist/my_package-0.1.0.tar.gz。接着用 twine 检查内容是否合规：
twine check dist/*
若提示 Failed validation，常见原因是 README.md 格式不被 PyPI 渲染器支持（比如用了 GitHub 特有语法），可临时转成 README.rst 或精简 Markdown。
四、注册账号并上传到 PyPI
访问 pypi.org/register 注册账号（注意：PyPI 和 TestPyPI 是两个独立站点）。上传前建议先用 TestPyPI 验证流程：
- 注册 TestPyPI 账号：test.pypi.org/register
- 配置
~/.pypirc（Linux/macOS）或%APPDATA%\pip\pip.ini（Windows）：
[distutils] index-servers = testpypi pypi <p>[testpypi] repository = <a href="https://www.php.cn/link/d690d0cd274a05efe2a0a58dac0d9461legacy/">https://www.php.cn/link/d690d0cd274a05efe2a0a58dac0d9461legacy/</a> username = <strong>token</strong> password = pypi-... # TestPyPI 生成的 API token</p><p>[pypi] repository = <a href="https://www.php.cn/link/14fab9101cde27b123722210d1a1836f">https://www.php.cn/link/14fab9101cde27b123722210d1a1836f</a> username = <strong>token</strong> password = pypi-... # PyPI 正式站 API token
生成 token 方法：登录 PyPI → Account Settings → API tokens → “Add API token”，限制 scope 可提高安全性。
上传命令：
twine upload --repository testpypi dist/* # 验证成功后，再上传正式版 twine upload --repository pypi dist/*
上传成功后，稍等 1–2 分钟，就能在 pypi.org/project/your-package-name 查看页面，并用 pip install your-package-name 安装测试。
不复杂但容易忽略：每次更新必须改 version 字段，否则 PyPI 拒绝重复版本；上传前务必 git tag 并 git push --tags，方便后续维护和溯源。
