本文详细讲解了 Python 项目从目录结构搭建、元数据配置、构建分发文件到上传至 PyPI 的全过程。涵盖了 pyproject.toml 配置、API Token 认证、Twine 工具使用以及安装验证方法，并补充了版本管理和常见错误排查的最佳实践，帮助开发者规范地发布和管理 Python 包。
本文介绍如何将开发完成的 Python 项目打包成可分发的格式，并上传至 Python 包索引（PyPI），以便他人通过 pip 安装使用。
首先确保本地安装了最新版本的 pip，以避免构建过程中的兼容性问题。
# Unix/macOS
python3 -m pip install --upgrade pip
# Windows
py -m pip install --upgrade pip
建议创建一个独立的虚拟环境进行开发和打包，避免污染全局环境。
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
推荐使用 src 布局来组织项目，这有助于隔离包代码与测试代码，减少导入错误。
packaging_tutorial/
└── src/
└── example_package_YOUR_USERNAME_HERE/
├── __init__.py
└── example.py
示例 example.py 内容：
def add_one(number):
"""返回输入数字加一的结果"""
return number + 1
现代 Python 项目推荐使用 pyproject.toml 替代传统的 setup.py。该文件定义了项目的依赖、元数据和构建后端。
常见的构建后端包括 hatchling, setuptools, flit_core 等。以下以 hatchling 为例：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
在 pyproject.toml 中添加 [project] 部分：
[project]
name = "example_package_your_username_here"
version = "0.0.1"
description = "一个用于演示的简单 Python 包"
readme = "README.md"
requires-python = ">=3.7"
authors = [
{ name="Example Author", email="[email protected]" },
]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.urls]
Homepage = "https://github.com/yourusername/example_package"
Documentation = "https://github.com/yourusername/example_package#readme"
注意事项：
.、_ 和 -。project.dependencies 列表中声明。提供项目说明，显示在 PyPI 页面上。
# Example Package
这是一个简单的示例包。
## 安装
pip install example-package-your-username-here
## 使用
from example_package import example
result = example.add_one(2)
print(result) # 输出 3
每个分发包都应包含许可证文件，明确用户使用条款。例如 MIT 许可证：
MIT License
Copyright (c) 2023 Your Name
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...
创建 tests/ 目录存放单元测试，虽然构建时不包含，但对维护至关重要。
使用 build 工具生成 .whl (Wheel) 和 .tar.gz (Source Distribution) 文件。
python3 -m pip install --upgrade build
python3 -m build
成功后会在 dist/ 目录下生成两个文件：
example_package-0.0.1-py3-none-any.whlexample_package-0.0.1.tar.gzhttps://test.pypi.org/。https://pypi.org/。由于安全策略更新，建议使用 API Token 而非用户名密码。
修改 ~/.pypirc 配置文件：
[testpypi]
username = __token__
password = pypi-AgENdGVzdC5weXBpLm9yZw...your_token_here
安装 Twine 工具：
python3 -m pip install --upgrade twine
上传至 TestPyPI：
python3 -m twine upload --repository testpypi dist/*
上传完成后，建议在独立环境中验证安装是否成功。
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-your-username-here
运行 Python 脚本测试功能：
from example_package import example
print(example.add_one(2)) # 预期输出 3
遵循语义化版本控制 (SemVer)，如 major.minor.patch。每次重大更新递增 major 号。
在上传前，务必在干净的环境中测试安装过程，确保依赖解析正确。
~/.pypirc 中的 token 是否正确，注意不要有多余空格。pyproject.toml 语法及构建后端依赖是否齐全。建议结合 GitHub Actions 等自动化工具，在代码推送后自动构建并发布，减少人工操作失误。
完成上述步骤后，您的 Python 项目即可被全球开发者通过 pip 安装使用。记得定期更新文档和维护依赖，确保包的长期可用性。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online