摘要：许多 Python 开发者，特别是初学者，都经历过这样的“甜蜜烦恼”：你写了一个很棒的脚本或小型应用，它在你的电脑上运行得完美无缺。但当你满怀信心地想要与他人分享时，问题就来了。用户反馈的不是你代码的逻辑错误，而是千奇百怪的“安装失败”。你开始怀疑人生：明明很
Python 打包和分发方面学到的惨痛教训
许多 Python 开发者，特别是初学者，都经历过这样的“甜蜜烦恼”：你写了一个很棒的脚本或小型应用，它在你的电脑上运行得完美无缺。但当你满怀信心地想要与他人分享时，问题就来了。用户反馈的不是你代码的逻辑错误，而是千奇百怪的“安装失败”。你开始怀疑人生：明明很简单的一件事，为什么如此困难？
我曾经也陷入这个困境。我决定将自己辛辛苦苦写的代码打包分享出去，结果却撞上了一堵无形的墙：Python 包的打包与分发。这看似简单的任务，让我花了一周时间挣扎在setup.py的报错、依赖地狱以及来自用户的“安装不了”的抱怨中。
在这篇文章中，我将毫无保留地分享我从无数次失败中总结出的宝贵经验。这些都是我在将 Python 项目从“个人玩具”变成“可供他人使用的工具”的过程中，一步步踩坑得来的教训。希望我的这些“硬核”经验，能帮助你避开那些常见的陷阱，让你的代码真正走向世界。
我最初的打包尝试，是手动编写setup.py文件。就像许多人一样，我从 Stack Overflow 上东拼西凑了一些代码片段，然后拼凑成一个看似可行的文件。结果呢？它在我的电脑上运行得好好的，但在其他任何地方都崩溃了。
我当时的setup.py看起来是这样的：
from setuptools import setupsetup( name="mypackage", version="0.1", packages=["mypackage"], install_requires=["numpy", "pandas"])初看之下，这个文件似乎没什么问题。但它缺少了许多至关重要的细节：详细的描述、分类器、Python 版本要求，以及可执行文件的入口点等。这些缺失的信息，就像是一本没有目录和封面的书，让使用者无从下手。
我的教训是： 仅仅能工作是不够的，你必须提供足够的元数据（metadata），让用户知道他们安装的是什么，以及它需要什么条件才能运行。一个更完整、更符合现代规范的setup.py应该包含所有必要的信息，例如：
from setuptools import setup, find_packagessetup( name="mypackage", version="0.1.0", description="一个有用的示例包", long_description=open("README.md").read, long_description_content_type="text/markdown", author="你的名字", author_email="你的邮箱@example.com", url="https://github.com/你的用户名/mypackage", packages=find_packages, python_requires=">=3.8", install_requires=[ "numpy>=1.21.0", "pandas>=1.3.0" ], entry_points={ "console_scripts": [ "mypackage=mypackage.cli:main" ] }, classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ],)这个更完善的版本不仅包含了项目名称和版本，还提供了详细描述、作者信息、项目主页、依赖关系、Python 版本要求，甚至还有用于可执行文件的入口点和软件分类信息。这就像给你的包加上了完整的说明书和身份信息，让它在茫茫的包海中脱颖而出，也让用户能够更放心地安装和使用。
核心要点：
文档化一切： 确保你的setup.py包含项目的完整元数据，例如描述、作者、许可证等。精确锁定版本： 仔细指定依赖项的版本，并使用版本范围来避免兼容性问题。包含元数据： 提供清晰的分类器（classifiers），让用户和工具能更好地理解你的包。早期的我，犯了一个最致命的错误之一：对依赖版本过于严格。我曾经将numpy的版本锁定为numpy==1.21.0，却没有意识到这会给那些需要numpy>=1.22的系统用户带来灾难性的后果。这就像你要求所有人都使用同一款老旧型号的手机才能安装你的应用，这显然是不现实的。
更明智的做法是使用版本范围，同时避免不必要的依赖。例如，可以这样指定依赖：
install_requires = [ "numpy>=1.21,=1.3,这告诉安装器，只要numpy的版本在 1.21 到 2.0 之间（不包含 2.0），都可以接受。这既保证了兼容性，又给了用户足够的灵活性。
此外，如果你的项目有可选功能，比如一些需要额外库才能使用的机器学习或开发功能，你应该使用extras_require。这可以让你将依赖项分组，用户只需安装他们需要的部分，而不是将所有依赖都一股脑地安装下来。
例如：
extras_require = { "dev": ["pytest", "black"], "ml": ["scikit-learn", "tensorflow"]}这样一来，用户可以根据自己的需要选择安装，比如pip install mypackage[ml]，这样就只会安装机器学习相关的依赖。这种方式让你的包更加灵活，也减轻了用户的安装负担。
核心要点：
版本范围优先： 尽量使用版本范围（例如>=1.21,按需安装： 利用extras_require来支持可选功能，让用户只安装他们需要的依赖。在与setup.py的反复斗争后，我发现 Python 社区正在转向一种新的、更现代的打包方式：PEP 517/518，其核心是pyproject.toml文件。
使用pyproject.toml最大的好处是，它让你的项目构建变得与工具无关。你可以用任何支持该标准的构建工具来打包你的项目，而不再局限于setuptools。这让整个打包流程变得更加清晰和标准化。
一个最小化的pyproject.toml示例是这样的：
[build-system]requires = ["setuptools>=61.0", "wheel"]build-backend = "setuptools.build_meta"[project]name = "mypackage"version = "0.1.0"description = "一个现代Python包"readme = "README.md"requires-python = ">=3.8"dependencies = [ "numpy>=1.21,=1.3,这个文件简洁明了，它定义了构建系统所需的依赖，以及项目的基本元数据和依赖关系。采用这种方式后，我的工作流变得更加干净、高效，并且与现代 Python 打包标准保持了一致。
我第一次将包推送到 PyPI 时，犯了一个菜鸟级别的错误：我上传了一个有问题的构建包。我没有在本地进行任何测试，就直接将其发布了。这就像没有试穿就将衣服卖给别人一样，必然会出问题。
PyPI 不允许删除已发布的版本，所以我的这个错误是永久性的，留下了不完美的记录。
从那以后，我养成了一个严格的工作习惯：在将包上传到 PyPI 之前，必须在本地进行完整测试。我现在的正确流程是这样的：
清除旧构建： 彻底删除之前的构建文件，确保所有东西都是最新生成的。重新构建： 使用python -m build命令生成一个全新的包文件。本地安装测试： 使用pip install dist/mypackage-0.1.0-py3-none-any.whl命令来本地安装这个生成的包，并检查它是否能正常工作。只有当我确认这个包在本地可以正确安装和运行时，我才会考虑将它推送到 PyPI。
核心要点：
先测试，再发布： 永远不要直接将包上传到 PyPI，本地安装测试是确保质量的最后一道防线。彻底清理： 在每次构建新版本前，确保清理掉所有旧的构建文件，以防混淆。我的另一个大错误是直接在 PyPI 上进行实验。我的第一次上传充满了拼写错误、文件缺失和版本冲突。由于 PyPI 不允许删除已发布的版本，这些“黑历史”就永远地留在了我的项目页面上。
从那以后，我学会了在TestPyPI上进行所有实验和测试。TestPyPI 是一个专门用于测试的包索引服务，它的使用方式与 PyPI 完全相同，但所有上传的包都只用于测试，不会污染正式环境。
上传到 TestPyPI 的命令如下：
# 上传到 TestPyPIpython -m twine upload --repository testpypi dist/*用户或者你自己可以从 TestPyPI 安装你的包，像这样：
pip install --index-url https://test.pypi.org/simple/ mypackage我的教训是： 将 PyPI 视作你的生产环境，而 TestPyPI 则是你的预发布环境或“沙盒”。在正式发布之前，先在 TestPyPI 上进行完整的测试，确保一切顺利。这能让你避免在正式环境中留下任何不必要的错误记录。
核心要点：
分清环境： PyPI 用于正式发布，TestPyPI 用于测试和实验。发布前预演： 在将包正式发布前，一定要在 TestPyPI 上进行预演，确保一切正常。我很快发现，如果我的一个次要更新（minor update）不小心破坏了用户的代码，他们会非常恼火。这让我意识到，版本号不仅仅是一个数字，它更是一种承诺。
遵循**语义化版本控制（Semantic Versioning，简称 SemVer）**完美解决了这个问题。它将版本号分为三部分：MAJOR.MINOR.PATCH。
PATCH：用于修复 bug，且不会破坏现有功能。例如，从0.1.1到0.1.2。MINOR：用于添加新功能，但仍然向下兼容。例如，从0.1.0到0.2.0。MAJOR：用于引入不兼容的重大变更。例如，从1.0.0到2.0.0。通过始终如一地遵循这个规则，我与用户之间建立了信任。他们知道，如果我发布一个次要版本更新，他们的代码不会因此崩溃。
手动将包上传到 PyPI 是一件既繁琐又容易出错的事情。我发现自己一遍又一遍地重复相同的命令：清除旧文件、构建新包、然后上传。
为了解决这个问题，我最终采用了 GitHub Actions 来自动化我的发布流程。现在，每当我在 GitHub 上创建一个新的 Release 时，这个自动化工作流就会被触发，它会自动构建我的包，并将其推送到 PyPI。
一个基本的 GitHub Actions 工作流文件看起来像这样：
name: Publish Python Packageon: release: types: [published]jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: '3.9' - name: Install dependencies run: pip install build twine - name: Build and publish run: | python -m build python -m twine upload dist/* env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}这个自动化脚本大大减少了我的工作量，也杜绝了因手动操作而产生的错误。
核心要点：
自动化一切： 利用 GitHub Actions 或其他 CI/CD 工具，自动化你的构建和发布流程，减少重复性工作。利用 Secrets 管理凭证： 不要将你的 PyPI 凭证硬编码在代码中，使用环境变量或 Secrets 来安全地管理它们。在我的经验中，编写出色的代码只是成功的一半。另一半，也是同样重要的一半，是确保这段代码对其他人来说是可用且可安装的。
我从最初的安装失败和依赖噩梦中，一路走来，最终实现了平稳的 PyPI 发布，赢得了用户的信任。
我学到的这些宝贵经验——明智地管理依赖、先本地测试、使用 TestPyPI、采用pyproject.toml、以及自动化发布流程——彻底改变了我分发 Python 项目的方式。
如果你也正在开始你的 Python 打包之旅，请做好心理准备，这可能会有一点“痛苦”。但一旦你掌握了这个流程，你将体会到作为一名 Python 开发者最令人兴奋的时刻之一：亲眼看着你的作品从你的笔记本电脑，走向成千上万用户的手中。
通过这八个关键经验，我希望你能够避开我曾经踩过的那些坑，更加顺畅地完成你的 Python 打包与分发之旅。从一个只在自己电脑上运行的脚本，到一个能够被社区广泛使用的工具，这不仅仅是技术的进步，更是心态的转变。
当你将代码打包并发布到 PyPI 时，你不仅仅是在分享一个文件，你是在为整个 Python 生态系统做出贡献。你正在将你的智慧和劳动，变成其他人可以依赖和使用的基石。
希望我的这些经验能够帮助你，让你的代码真正走向更广阔的世界，让更多人从中受益。
来源：高效码农
