将Python项目发布到PyPI官方仓库的详细步骤

Hazel
Hazel
发布时间:2026-11-18 | 4人浏览过
原创

详细讲解将Python项目发布到PyPI官方仓库的完整操作流程,涵盖src目录规范、pyproject.toml现代化配置、打包构建、API Token与Trusted Publisher认证、TestPyPI测试以及生产环境发布和版本迭代。

将自己编写的 Python 代码发布到官方包索引仓库 PyPI(Python Package Index),可以让全球开发者通过一条简短的 pip install 你的包名 直接获取并集成你的成果。现代 Python 打包标准已全面转向以 pyproject.toml 为基石的声明式配置。完成一个高质量项目的正式发布,核心包含五个阶段:组织规范的项目目录、编写现代化元数据配置文件、在本地构建源码包与二进制轮子、在测试环境验证分发与安装,以及最终使用安全凭据发布至 PyPI 官方平台。

将Python项目发布到PyPI官方仓库的详细步骤
图 1:从本地代码整理到 PyPI 官方正式上线的关键路径图

一、组织规范的项目结构

在准备发布前,首先需要保证项目的文件布局清晰、分工明确。在 Python 打包生态中,推荐使用 src/ 布局(src-layout)。这种结构能有效防止本地开发目录污染 Python 的导入路径,确保在执行单元测试或导入检查时,所测试的代码必须是真正构建并安装到虚拟环境中的包,避免“本地运行正常但分发后缺少文件”的问题。

标准的项目目录示例如下:

my_package_project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

各个主要文件的职责说明:

  • src/my_package/:核心源代码目录。必须包含 __init__.py,用于标识这是一个合法的 Python 模块包。
  • pyproject.toml:项目的配置中枢,包含构建系统说明、项目元数据(包名、版本、作者等)以及外部依赖。
  • README.md:项目的详细说明文档。PyPI 会直接将其渲染为项目主页的说明内容。
  • LICENSE:开源协议文本(如 MIT、Apache-2.0),明确使用者的权利与限制。
  • tests/:项目的自动化测试代码,打包发布时通常不随 wheel 分发,但会保留在 sdist 源码包中。

二、配置现代化的 pyproject.toml 文件

过去 Python 社区普遍依赖 setup.py 执行命令式打包,这种方式容易在构建阶段执行任意外部脚本,给环境一致性和安全性带来隐患。现代打包规范(PEP 517 / PEP 518 / PEP 621)推荐完全采用声明式的 pyproject.toml 文件。

以下是一个推荐且完整的 pyproject.toml 配置模版(以成熟的 hatchling 作为构建后端为例):

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my_sample_tool"
version = "0.1.0"
description = "A lightweight utility for demonstration purpose."
readme = "README.md"
requires-python = ">=3.8"
license = { text = "MIT" }
authors = [
  { name = "Author Name", email = "author@example.com" },
]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
dependencies = [
    "requests >= 2.28.0",
]

[project.urls]
Homepage = "https://github.com/username/my_sample_tool"
Issues = "https://github.com/username/my_sample_tool/issues"

[project.scripts]
my-cli = "my_package.core:main"

关键字段解析:

  • [build-system]:指明打包所需的构建工具链。除 hatchling 外,也可以选择 flit-core 或 setuptools。
  • name:在 PyPI 上的唯一包名。在 PyPI 中,包名不区分大小写,且连字符 - 与下划线 _ 被规范化为同一标识,发布前须先在官网检索确认未被占用。
  • version:项目版本号,通常遵循语义化版本格式(主版本.次版本.修订号)。
  • dependencies:声明安装该包时必需的第三方运行时依赖。用户执行 pip install 时会自动下载解析这些依赖。
  • [project.scripts]:可选字段。如果项目提供了命令行工具,可在此配置命令名称与对应调用的 Python 函数。
将Python项目发布到PyPI官方仓库的详细步骤
图 2:pyproject.toml 配置经由构建引擎转换为两大标准分发包的过程

三、构建项目分发包

在发布前,必须在本地把代码打包成标准的分发文件。现代官方推荐的构建工具是 build(由 Python 打包权威机构 PyPA 维护)。

1. 安装构建工具

python -m pip install --upgrade build

2. 执行构建命令

在包含 pyproject.toml 的项目根目录下运行:

python -m build

执行完毕后,项目根目录下会自动生成一个名为 dist/ 的目录,里面包含两类文件:

  • my_sample_tool-0.1.0.tar.gz:源码分发包(Source Distribution,简称 sdist)。
  • my_sample_tool-0.1.0-py3-none-any.whl:二进制分发包(Wheel 格式)。
概念辨析:为什么必须同时构建 sdist 和 wheel?

部分初学者会疑惑是否只需上传 .whl。实际上,wheel 是预构建格式,客户端安装时无需执行编译脚本,安装速度极快;而 sdist 包含原始源码与元数据,是纯粹的后备资源。当某些用户处于特殊架构、没有对应预编译 Wheel 或需要对源代码进行安全审查时,pip 会自动拉取 sdist 在本地完成构建。两者同时提供是 PyPA 官方强烈推荐的最佳实践。

四、配置 PyPI 账户与安全认证凭据

随着软件供应链安全标准的升级,PyPI 官方已强制推行双因素认证(2FA),并全面废弃了在上传时使用普通账户密码的传统机制。目前支持两种安全的认证发布方式:API Token 与 Trusted Publishers。

将Python项目发布到PyPI官方仓库的详细步骤
图 3:PyPI 凭据认证的演进与现代安全上传方式

获取 API Token 的具体步骤

  1. 打开 pypi.org 并登录你的账户(若无账号需先注册并绑定手机或硬件认证器完成 2FA 设置)。
  2. 点击右上角个人头像,进入 Account settings。
  3. 向下滚动至 API tokens 区域,点击 Add API token。
  4. 在 Token name 中输入标识(如 my-release-token)。
  5. 在 Scope 栏位:由于项目尚未在 PyPI 建立,首次发布时需选择 Entire account (all projects);一旦初次发布成功,建议进入该 Token 设置将其限制为该项目专属,或生成单一项目 Scope 的新 Token。
  6. 点击生成并复制该 Token(以 pypi- 开头,只展示一次,务必安全保存)。

五、在测试沙箱 TestPyPI 进行预发布演练

在直接推送到正式的 PyPI 之前,强烈建议先在官方测试仓库 TestPyPI 上进行演练。PyPI 遵循极其严格的“版本号不可篡改原则(Immutability)”:任何一个版本的包一旦上传成功,哪怕立即在后台删除,该包名下的同一个版本号也永远不能再次使用。如果在生产环境因缺少依赖文件或格式报错,就不得不强行升级版本号(例如从 0.1.0 变成 0.1.1),影响版本记录的整洁。

1. 注册 TestPyPI 独立账号并生成 Token

访问 test.pypi.org。注意:TestPyPI 的数据库与正式 PyPI 彼此隔离,两者的账号并不互通,需要单独注册、开启 2FA 并生成测试专用的 API Token。

2. 使用 twine 检验包完整性

安装上传工具 twine:

python -m pip install --upgrade twine

在上传前,运行语法与元数据校验:

twine check dist/*

若终端输出 Checking dist/...: PASSED,表示包元数据与 README 渲染校验通过。

3. 上传分发包到 TestPyPI

python -m twine upload --repository testpypi dist/*

执行后终端会提示输入认证凭据:

  • Username:输入 __token__(固定字符串,前后为双下划线)。
  • Password:粘贴在 TestPyPI 生成的以 pypi- 开头的测试 Token。

4. 在隔离虚拟环境中验证安装

包上传成功后,新建一个独立的虚拟环境进行验证。由于 TestPyPI 仅用于测试,其上面可能缺少项目所需的第三方运行时依赖(如 requests),因此需要通过 --extra-index-url 指定正式 PyPI 作为依赖补充源:

# 创建并激活一个临时的纯净测试虚拟环境
python -m venv test_env
source test_env/bin/activate  # Windows 用户执行: test_env\Scripts\activate

# 从 TestPyPI 安装目标包,并从官方 PyPI 下载必要依赖
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ my_sample_tool

安装完成后,启动 python 解释器测试导入或运行 CLI 命令:

python -c "import my_package; print(my_package.__file__)"

若能正常加载并输出路径,说明包结构完整,元数据无误。

六、正式发布至 PyPI 官方仓库

在测试环境验证无误后,即可向全球公开的正式仓库进行发布。

1. 清理并重新构建(如有调整)

如果在此前测试中修改了代码或配置,务必先清空旧的构建产物,再重新构建:

# 清空旧产物
rm -rf dist/ build/ *.egg-info

# 重新生成干净的分发包
python -m build

2. 上传至正式 PyPI

python -m twine upload dist/*

在终端交互中输入:

  • Username:__token__
  • Password:正式 PyPI 账号生成的 API Token(pypi-...)

上传成功后,Twine 会在控制台输出项目在 PyPI 上的正式访问页面链接,格式类似:

View at:
https://pypi.org/project/my_sample_tool/0.1.0/

3. 全网可用性验证

通常在上传成功后数秒至一分钟内,PyPI 全球 CDN 即可完成同步。可在本地任何正常的 Python 环境中直接执行:

pip install my_sample_tool

核对已安装包的版本与预期一致即可。

将Python项目发布到PyPI官方仓库的详细步骤
图 4:PyPI 常见错误诊断与标准的版本迭代更新模型

七、后续版本维护与注意事项

初次发布成功后,后续的代码更新与维护需遵循以下规范:

场景与需求 规范做法 注意事项
修复 Bug 或打补丁 递增修订号(如 0.1.0 ➔ 0.1.1) 不得修改已发布的任何文件,必须递增版本重新打包。
新增向下兼容的功能 递增次版本号(如 0.1.1 ➔ 0.2.0) 确保旧版 API 继续有效,在文档中增补新功能说明。
发生重大不兼容更新 递增主版本号(如 0.2.0 ➔ 1.0.0) 在 README 中清晰标注破坏性变更与迁移指引。
凭据权限收紧 在 PyPI 将 Token Scope 改为专属项目 防止由于通用 Token 泄露导致其他项目遭受恶意篡改。

综上所述,遵循现代规范的 Python 打包体系,是以 pyproject.toml 声明元数据为基石,通过 build 生成高质量的 sdist 和 wheel,并在严格认证与沙箱演练的配合下将包发布至 PyPI。建立起这套标准化的流程后,后续无论手工迭代还是集成至 GitHub Actions 进行自动化持续发布,都能保证发布过程的高效与可靠。

相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表