1. 从“源码分发”到“二进制分发”为什么需要whl文件如果你写过Python脚本或者用过pip install那你大概率已经和whl文件打过交道了只是你可能没意识到。回想一下当你安装numpy或pandas这种大型库时是不是感觉比安装一些纯Python的小库要快得多这背后的功臣往往就是whl文件。whl文件全称是Wheel文件你可以把它理解成Python世界的“安装包”或“软件包”。在Wheel格式出现之前Python社区主要依赖的是egg文件和sdist源码分发即.tar.gz文件。源码分发意味着当你执行pip install some-package时pip会下载一个压缩包里面是项目的源代码、setup.py等文件然后在你的本地机器上现场编译、构建、安装。这个过程有几个明显的痛点速度慢对于包含C/C扩展比如用Cython写的或者需要调用C库的的项目每次安装都需要调用本地的C编译器如gcc、MSVC进行编译。编译一个像numpy这样的大型库可能需要好几分钟甚至更久。环境依赖复杂编译需要一整套正确的构建环境。在Windows上你可能需要安装Visual Studio Build Tools在Linux上需要gcc、python3-dev等开发包。缺少任何一个环节安装都会失败并抛出一堆令人困惑的错误信息。可重复性差由于是在用户机器上现场编译编译结果可能因为编译器版本、系统库版本、甚至CPU指令集的微小差异而不同这为软件部署和一致性带来了挑战。Wheel格式就是为了解决这些问题而生的。它本质上是一个预编译的二进制分发格式。作为项目开发者你可以在拥有完整构建环境的机器上比如CI/CD服务器一次性将项目打包成whl文件。这个whl文件里已经包含了编译好的扩展模块.so、.pyd、.dylib、纯Python代码、以及所有必要的元数据如包名、版本、依赖关系。用户拿到这个whl文件后安装过程就变成了简单的文件解压和复制到site-packages目录速度极快且无需任何编译工具链。所以为你的Python项目生成whl文件不仅仅是一个“打包”动作更是将你的项目从“源代码”形态升级为“产品”形态的关键一步。它意味着你的用户可以更简单、更快速、更可靠地安装你的软件极大地提升了用户体验和部署效率。无论是发布到PyPI供全球开发者使用还是在企业内部进行分发包whl都是目前Python生态中事实上的标准分发格式。2. 打包基石深入理解pyproject.toml与setup.py/setup.cfg要打包whl你必须理解项目的“配置清单”。过去这个清单主要是setup.py但现在更现代、更推荐的方式是使用pyproject.toml。我们先从核心概念讲起。2.1pyproject.toml现代项目的统一入口pyproject.toml是PEP 518引入的配置文件旨在为Python项目提供一个统一的、声明式的配置中心。它最重要的作用是告诉构建工具如setuptools,flit,poetry这个项目应该如何被构建。一个最基础的、用于setuptools的pyproject.toml长这样[build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta这三行是必须的它们定义了[build-system]: 声明构建系统配置的节。requires: 列出构建本项目所需的最小依赖包集合。这里我们指定需要setuptools和wheel。wheel包提供了生成whl文件的能力。build-backend: 指定实际执行构建的后端。setuptools.build_meta是setuptools提供的标准后端。有了这个文件当用户或CI系统在任何干净的环境中使用pip install .或python -m build时pip会首先创建一个独立的虚拟环境并在其中安装requires列表里的包setuptools和wheel然后再调用指定的build-backend来执行构建和安装。这保证了构建过程的环境一致性。2.2 项目元数据[project]与[tool.setuptools]项目本身的元数据如名称、版本、作者等在pyproject.toml中通过[project]节来声明。这是PEP 621标准化的方式。[project] name my-awesome-package version 0.1.0 authors [ {name Your Name, email youexample.com}, ] description A short description of my awesome package. readme README.md license {text MIT} classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ] dependencies [ requests2.25.0, numpy1.20.0, ] [project.optional-dependencies] dev [ pytest6.0, black22.0, ]关键字段解析name: 包名在PyPI上必须唯一。建议使用小写字母、数字和连字符。version: 遵循语义化版本规范SemVer。这是一个非常重要的字段每次发布新包都必须更新。dependencies: 你的包运行时所依赖的其他包。用户安装你的包时这些依赖会被自动安装。[project.optional-dependencies]: 定义可选依赖组。例如dev组包含了开发时需要的工具测试、代码格式化。用户可以通过pip install “my-awesome-package[dev]”来安装这些额外依赖。那么你的源代码文件.py文件在哪里告诉构建工具呢对于纯Python项目setuptools默认会自动发现所有包。但如果你有更复杂的结构或者需要包含数据文件就需要使用[tool.setuptools]节。[tool.setuptools] packages [mypkg, mypkg.subpkg] # 显式指定包 # 或者使用自动发现 # packages find: # 这会自动查找所有包 # package-dir { src} # 如果你的包在src目录下 [tool.setuptools.package-data] # 指定需要包含的非Python文件数据文件 mypkg [data/*.json, templates/*.html]2.3 传统方式setup.py的动态配置虽然pyproject.toml是未来但很多现有项目仍在使用setup.py。它是一个可执行的Python脚本允许你动态地配置构建参数。from setuptools import setup, find_packages setup( namemy-awesome-package, version0.1.0, authorYour Name, author_emailyouexample.com, descriptionA short description, long_descriptionopen(README.md).read(), long_description_content_typetext/markdown, packagesfind_packages(wheresrc), # 自动发现包 package_dir{: src}, # 包根目录在src下 install_requires[ requests2.25.0, numpy1.20.0, ], extras_require{ dev: [pytest6.0, black22.0], }, classifiers[ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ], python_requires3.8, )setup.pyvspyproject.toml如何选择新项目无脑选pyproject.toml它更简洁、声明式、易于静态分析是社区推动的方向。旧项目迁移可以逐步迁移先添加pyproject.toml定义构建系统元数据可以暂时保留在setup.py或setup.cfg中。最终目标是所有配置都进入pyproject.toml。需要极端动态配置时如果你的版本号需要从Git标签动态读取或者包列表需要根据条件生成setup.py的灵活性仍有价值。但通常可以通过pyproject.toml配合一些构建钩子Hooks来实现。实操心得版本管理陷阱千万不要在setup.py或pyproject.toml里用__version__从一个被安装的模块里导入版本号这会造成循环依赖。构建工具需要读取版本号来决定打包什么而此时你的包可能还没被安装。最佳实践是将版本号单独维护在一个文件中如src/mypkg/__init__.py里写__version__ “0.1.0”然后在pyproject.toml中通过dynamic [“version”]配合[tool.setuptools.dynamic]节或者使用importlib.metadata在后置钩子中读取。更简单的做法是使用setuptools-scm它能自动从Git标签和提交历史中推导出版本号强烈推荐。3. 构建工具链实战从setuptools到build配置好项目元数据后我们就可以开始构建了。这里介绍两种最核心的构建方式。3.1 经典方式直接使用setuptools如果你已经安装了setuptools和wheel可以在项目根目录运行python setup.py bdist_wheel这条命令会做以下几件事执行setup.py脚本读取配置。准备构建目录通常是build/。将你的源代码包可能包括编译扩展按照指定规则复制或编译到构建目录。调用wheel包的功能将构建目录的内容打包成一个.whl文件并输出到dist/目录。生成的whl文件名会包含包名、版本、Python标签如py3、ABI标签如none和平台标签如any,win_amd64。例如my_awesome_package-0.1.0-py3-none-any.whl。其中py3-none-any表示这是一个纯Python的、跨平台的wheel。对于包含C扩展的项目情况会复杂一些。你需要确保系统有正确的编译环境Windows上通常是Visual Studio或MSVCLinux/macOS上是GCC/Clang。setuptools通过Extension类来定义C扩展# 在setup.py中 from setuptools import setup, Extension module Extension(mypkg.speedup, sources[src/mypkg/speedup.c], include_dirs[/usr/local/include]) setup( ..., ext_modules[module], )运行python setup.py bdist_wheel时setuptools会调用编译器来编译这个C文件。生成的whl文件名会包含平台信息如my_awesome_package-0.1.0-cp39-cp39-win_amd64.whl这意味着它只能在Windows 64位、CPython 3.9的环境下安装。3.2 现代标准方式使用python -m buildPEP 517和518定义了更标准的构建流程不直接调用setup.py而是通过pyproject.toml中指定的构建后端来执行。build包就是这个流程的官方前端工具。首先安装构建工具pip install build然后在项目根目录执行python -m build --wheel这个命令会创建一个独立的、临时的虚拟环境隔离构建环境。根据pyproject.toml中的[build-system]部分安装requires里指定的依赖setuptools和wheel。调用build-backendsetuptools.build_meta来构建wheel。将生成的wheel文件输出到dist/目录。为什么推荐python -m build隔离性构建环境是干净的避免了因全局环境污染导致的构建失败。可重复性在任何机器上只要pyproject.toml一致构建过程就是一致的。标准化它是PEP标准未来所有构建工具都会遵循这个接口。踩坑实录editable安装模式与wheel开发时我们常用pip install -e .可编辑安装这会在site-packages里创建一个链接指向你的源码目录方便边改边测。但请注意可编辑安装模式不会生成wheel文件。它创建的是一个特殊的.egg-link文件或*.pth文件。当你需要分发、测试真正的安装效果时务必先构建wheelpython -m build --wheel然后用pip install dist/your_package.whl来安装这样才能模拟用户真实的安装场景避免一些路径或导入相关的问题在最后时刻才暴露。4. 高级打包场景与疑难排坑掌握了基础打包后你会遇到更实际、更复杂的需求。下面我们拆解几个典型场景。4.1 包含数据文件与资源你的包可能不只是Python代码还需要包含模板、静态文件CSS/JS、预训练模型、默认配置文件等。这些统称为“包数据”Package Data。在pyproject.toml中配置推荐 使用[tool.setuptools.package-data]节进行声明式配置如前面2.2节所示。键是包名值是该包下需要包含的文件路径列表支持通配符。在setup.py中配置 使用package_data参数。setup( ..., package_data{ mypkg: [data/*.json, templates/*.html], mypkg.subpkg: [config/*.yaml], }, include_package_dataTrue, # 同时启用MANIFEST.in文件 )MANIFEST.in文件这是一个更古老但依然有效的机制用于指定在构建源码分发sdist时要包含哪些额外的文件。setuptools在构建wheel时默认也会参考MANIFEST.in但为了清晰和避免混淆对于纯数据文件我强烈建议仅使用package_data配置。MANIFEST.in更适合包含像LICENSE、README.md、tests/等不属于任何Python包但又需要被打进源码包的文件。如何在代码中访问这些数据文件不能直接用相对路径./data/file.json因为安装后文件位置会变。正确的方法是使用importlib.resourcesPython 3.7或pkg_resources较旧但功能更全。# 使用 importlib.resources (现代推荐) import importlib.resources as pkg_resources from mypkg import data # data是一个包含数据文件的子包或目录 # 作为文件路径需要上下文管理器 with pkg_resources.as_file(pkg_resources.files(data).joinpath(config.json)) as config_path: with open(config_path, r) as f: config json.load(f) # 或直接读取内容 config_text pkg_resources.files(data).joinpath(config.json).read_text(encodingutf-8)4.2 处理依赖与可选功能依赖管理是打包的重要一环。install_requires/dependencies这是硬依赖没有它们你的包无法运行。版本范围要写清楚。使用表示最低版本~表示兼容版本如~2.1.0等价于2.1.0, 2.2.0避免使用过于宽泛的*。extras_require/optional-dependencies定义可选功能依赖。例如你的包基础功能只需要requests但有一个需要pandas进行数据分析的模块。你可以定义[project.optional-dependencies] analysis [pandas1.3.0]用户可以通过pip install “my-package[analysis]”来安装这个额外功能。在代码中可以通过try-except导入来提供优雅降级。setup_requires已废弃。用于指定构建时依赖现在应统一在pyproject.toml的[build-system]下的requires中声明。tests_require用于指定运行测试的依赖通常放在extras_require的dev或test组里。4.3 平台特定与条件依赖如果你的包只在特定平台工作或者在不同平台需要不同的依赖可以使用环境标记Environment Markers。[project] dependencies [ pywin32300; sys_platform win32, # 仅Windows需要 pyobjc-core8.0; sys_platform darwin, # 仅macOS需要 some-lib1.0; python_version 3.8, # Python 3.8 需要 ]在setup.py中写法类似install_requires[ pywin32300; sys_platform win32, ]4.4 常见构建错误与排查error: invalid command bdist_wheel原因没有安装wheel包。解决pip install wheel。ModuleNotFoundError: No module named setuptools或Cant findpyproject.tomlorsetup.py原因在错误的目录执行命令或者pyproject.toml中[build-system]配置错误。解决确保在包含pyproject.toml或setup.py的项目根目录运行命令。检查pyproject.toml格式是否正确。打包成功但安装后import失败提示找不到模块原因packages配置错误没有包含你的源码包。或者包结构不符合预期例如使用了src布局但未配置package_dir。排查检查dist/下的whl文件内容unzip -l dist/my_package.whl。看看你的.py文件是否在正确的路径下如my_package/__init__.py。检查pyproject.toml中的[tool.setuptools]或setup.py中的packages和package_dir设置。对于src布局务必设置package_dir {“”: “src”}并使用find_packages(where”src”)。包含C扩展的项目在Windows上构建失败提示Unable to find vcvarsall.bat原因缺少Windows C编译环境。解决方案A推荐安装Visual Studio Build Tools或Visual Studio并勾选“使用C的桌面开发”工作负载。方案B使用预编译的二进制wheel。对于开源项目可以借助CI如GitHub Actions在多种平台上自动构建并上传到PyPI。对于私有项目可以维护一个内部的wheel仓库。版本冲突或依赖解析失败原因你的包声明的依赖版本与用户环境中已安装的包版本冲突。解决在声明依赖时尽量使用宽松但合理的版本范围。使用pip的依赖解析器虽然现在更强大但过于严格的版本限制如2.1.0仍可能给用户带来麻烦。除非有绝对必要否则使用和~。5. 从构建到发布完整工作流与最佳实践构建出whl文件只是第一步一个专业的打包发布流程还包括测试、上传和版本管理。5.1 本地测试与验证在发布前务必进行安装测试# 1. 在全新的虚拟环境中测试安装 python -m venv test_env source test_env/bin/activate # Linux/macOS # test_env\Scripts\activate # Windows pip install dist/my_awesome_package-0.1.0-py3-none-any.whl # 2. 启动Python尝试导入你的包并运行核心功能 python -c “import my_awesome_package; print(my_awesome_package.__version__)” # 运行你的测试套件如果随包安装了 python -m pytest --pyargs my_awesome_package使用tox进行多环境测试tox可以自动为你创建多个虚拟环境例如Python 3.8, 3.9, 3.10在每个环境中构建并安装你的包然后运行测试。这是确保包兼容性的黄金标准。配置一个简单的tox.ini[tox] envlist py38, py39, py310, py311 [testenv] deps pytest6.0 commands python -m pytest tests/运行tox即可。5.2 发布到PyPIPyPI是Python包的官方仓库。发布前你需要注册一个账号。使用twine上传安全推荐安装twinepip install twine构建分发文件源码包和wheel包python -m build上传到测试PyPI先试水twine upload --repository-url https://test.pypi.org/legacy/ dist/*从测试PyPI安装验证pip install --index-url https://test.pypi.org/simple/ my-awesome-package确认无误后上传到正式PyPItwine upload dist/*你需要输入在PyPI上注册的用户名和密码。为了提高安全性建议使用API Token。在PyPI账户设置中生成Token上传时用户名填__token__密码填Token本身。自动化发布与CI/CD 对于开源项目最酷的做法是使用GitHub Actions。你可以配置一个工作流在每次打上Git标签如v0.1.0时自动运行测试、构建wheel并上传到PyPI。网上有大量现成的模板搜索“GitHub Actions Python publish”即可找到。5.3 版本管理与“开发版”打包版本号管理至关重要。我强烈推荐使用setuptools-scm。它可以根据Git仓库的标签和提交历史自动生成版本号。安装pip install setuptools-scm在pyproject.toml中配置[project] name “my-awesome-package” dynamic [“version”] # 声明版本是动态的 [tool.setuptools.dynamic] version {attr “mypkg.__version__”} # 从包中读取需要配合setuptools-scm [tool.setuptools_scm] # setuptools-scm的配置 # 通常无需额外配置默认行为就很好在src/mypkg/__init__.py中如果你用src布局from importlib.metadata import version, PackageNotFoundError try: __version__ version(__name__) except PackageNotFoundError: # 包没有被安装例如在开发模式下 __version__ “0.0.0dev”为发布打标签git tag -a v0.1.0 -m “Release version 0.1.0”然后git push --tags。当你构建时setuptools-scm会自动将标签v0.1.0转换为版本号0.1.0。如果当前提交距离标签还有额外的提交它会生成类似0.1.1.dev5gabc123的开发版本号。对于日常开发你可能不想每次都打标签。可以直接安装为“可编辑模式”pip install -e .进行开发。当需要测试“准发布”状态时再构建wheel进行安装测试。5.4 私有包分发搭建内部PyPI对于公司内部项目你不可能都发布到公开PyPI。这时需要搭建私有PyPI服务器。有几个成熟选择pypiserver轻量级适合小团队。一个命令就能启动。devpi功能强大支持缓存、镜像、持续集成等是更专业的选择。云服务/商业产品如Gemfury、Cloudsmith等提供托管的私有仓库服务。使用私有仓库时用户可以通过pip的--index-url或--extra-index-url参数来指定源或者在pip.conf文件中进行永久配置。打包Python项目成whl文件远不止是运行一条命令。它涉及项目结构的规划、依赖的精准声明、构建流程的标准化以及最终的分发策略。从简单的纯Python库到复杂的带C扩展的项目理解并善用pyproject.toml、setuptools、wheel和build这套工具链能让你交付的软件更加专业、可靠。记住一个好的打包实践是对你代码用户的一份尊重也是项目迈向成熟的重要标志。
Python项目打包实战：从pyproject.toml到whl文件构建与发布
发布时间：2026/7/29 10:37:37
1. 从“源码分发”到“二进制分发”为什么需要whl文件如果你写过Python脚本或者用过pip install那你大概率已经和whl文件打过交道了只是你可能没意识到。回想一下当你安装numpy或pandas这种大型库时是不是感觉比安装一些纯Python的小库要快得多这背后的功臣往往就是whl文件。whl文件全称是Wheel文件你可以把它理解成Python世界的“安装包”或“软件包”。在Wheel格式出现之前Python社区主要依赖的是egg文件和sdist源码分发即.tar.gz文件。源码分发意味着当你执行pip install some-package时pip会下载一个压缩包里面是项目的源代码、setup.py等文件然后在你的本地机器上现场编译、构建、安装。这个过程有几个明显的痛点速度慢对于包含C/C扩展比如用Cython写的或者需要调用C库的的项目每次安装都需要调用本地的C编译器如gcc、MSVC进行编译。编译一个像numpy这样的大型库可能需要好几分钟甚至更久。环境依赖复杂编译需要一整套正确的构建环境。在Windows上你可能需要安装Visual Studio Build Tools在Linux上需要gcc、python3-dev等开发包。缺少任何一个环节安装都会失败并抛出一堆令人困惑的错误信息。可重复性差由于是在用户机器上现场编译编译结果可能因为编译器版本、系统库版本、甚至CPU指令集的微小差异而不同这为软件部署和一致性带来了挑战。Wheel格式就是为了解决这些问题而生的。它本质上是一个预编译的二进制分发格式。作为项目开发者你可以在拥有完整构建环境的机器上比如CI/CD服务器一次性将项目打包成whl文件。这个whl文件里已经包含了编译好的扩展模块.so、.pyd、.dylib、纯Python代码、以及所有必要的元数据如包名、版本、依赖关系。用户拿到这个whl文件后安装过程就变成了简单的文件解压和复制到site-packages目录速度极快且无需任何编译工具链。所以为你的Python项目生成whl文件不仅仅是一个“打包”动作更是将你的项目从“源代码”形态升级为“产品”形态的关键一步。它意味着你的用户可以更简单、更快速、更可靠地安装你的软件极大地提升了用户体验和部署效率。无论是发布到PyPI供全球开发者使用还是在企业内部进行分发包whl都是目前Python生态中事实上的标准分发格式。2. 打包基石深入理解pyproject.toml与setup.py/setup.cfg要打包whl你必须理解项目的“配置清单”。过去这个清单主要是setup.py但现在更现代、更推荐的方式是使用pyproject.toml。我们先从核心概念讲起。2.1pyproject.toml现代项目的统一入口pyproject.toml是PEP 518引入的配置文件旨在为Python项目提供一个统一的、声明式的配置中心。它最重要的作用是告诉构建工具如setuptools,flit,poetry这个项目应该如何被构建。一个最基础的、用于setuptools的pyproject.toml长这样[build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta这三行是必须的它们定义了[build-system]: 声明构建系统配置的节。requires: 列出构建本项目所需的最小依赖包集合。这里我们指定需要setuptools和wheel。wheel包提供了生成whl文件的能力。build-backend: 指定实际执行构建的后端。setuptools.build_meta是setuptools提供的标准后端。有了这个文件当用户或CI系统在任何干净的环境中使用pip install .或python -m build时pip会首先创建一个独立的虚拟环境并在其中安装requires列表里的包setuptools和wheel然后再调用指定的build-backend来执行构建和安装。这保证了构建过程的环境一致性。2.2 项目元数据[project]与[tool.setuptools]项目本身的元数据如名称、版本、作者等在pyproject.toml中通过[project]节来声明。这是PEP 621标准化的方式。[project] name my-awesome-package version 0.1.0 authors [ {name Your Name, email youexample.com}, ] description A short description of my awesome package. readme README.md license {text MIT} classifiers [ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ] dependencies [ requests2.25.0, numpy1.20.0, ] [project.optional-dependencies] dev [ pytest6.0, black22.0, ]关键字段解析name: 包名在PyPI上必须唯一。建议使用小写字母、数字和连字符。version: 遵循语义化版本规范SemVer。这是一个非常重要的字段每次发布新包都必须更新。dependencies: 你的包运行时所依赖的其他包。用户安装你的包时这些依赖会被自动安装。[project.optional-dependencies]: 定义可选依赖组。例如dev组包含了开发时需要的工具测试、代码格式化。用户可以通过pip install “my-awesome-package[dev]”来安装这些额外依赖。那么你的源代码文件.py文件在哪里告诉构建工具呢对于纯Python项目setuptools默认会自动发现所有包。但如果你有更复杂的结构或者需要包含数据文件就需要使用[tool.setuptools]节。[tool.setuptools] packages [mypkg, mypkg.subpkg] # 显式指定包 # 或者使用自动发现 # packages find: # 这会自动查找所有包 # package-dir { src} # 如果你的包在src目录下 [tool.setuptools.package-data] # 指定需要包含的非Python文件数据文件 mypkg [data/*.json, templates/*.html]2.3 传统方式setup.py的动态配置虽然pyproject.toml是未来但很多现有项目仍在使用setup.py。它是一个可执行的Python脚本允许你动态地配置构建参数。from setuptools import setup, find_packages setup( namemy-awesome-package, version0.1.0, authorYour Name, author_emailyouexample.com, descriptionA short description, long_descriptionopen(README.md).read(), long_description_content_typetext/markdown, packagesfind_packages(wheresrc), # 自动发现包 package_dir{: src}, # 包根目录在src下 install_requires[ requests2.25.0, numpy1.20.0, ], extras_require{ dev: [pytest6.0, black22.0], }, classifiers[ Programming Language :: Python :: 3, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ], python_requires3.8, )setup.pyvspyproject.toml如何选择新项目无脑选pyproject.toml它更简洁、声明式、易于静态分析是社区推动的方向。旧项目迁移可以逐步迁移先添加pyproject.toml定义构建系统元数据可以暂时保留在setup.py或setup.cfg中。最终目标是所有配置都进入pyproject.toml。需要极端动态配置时如果你的版本号需要从Git标签动态读取或者包列表需要根据条件生成setup.py的灵活性仍有价值。但通常可以通过pyproject.toml配合一些构建钩子Hooks来实现。实操心得版本管理陷阱千万不要在setup.py或pyproject.toml里用__version__从一个被安装的模块里导入版本号这会造成循环依赖。构建工具需要读取版本号来决定打包什么而此时你的包可能还没被安装。最佳实践是将版本号单独维护在一个文件中如src/mypkg/__init__.py里写__version__ “0.1.0”然后在pyproject.toml中通过dynamic [“version”]配合[tool.setuptools.dynamic]节或者使用importlib.metadata在后置钩子中读取。更简单的做法是使用setuptools-scm它能自动从Git标签和提交历史中推导出版本号强烈推荐。3. 构建工具链实战从setuptools到build配置好项目元数据后我们就可以开始构建了。这里介绍两种最核心的构建方式。3.1 经典方式直接使用setuptools如果你已经安装了setuptools和wheel可以在项目根目录运行python setup.py bdist_wheel这条命令会做以下几件事执行setup.py脚本读取配置。准备构建目录通常是build/。将你的源代码包可能包括编译扩展按照指定规则复制或编译到构建目录。调用wheel包的功能将构建目录的内容打包成一个.whl文件并输出到dist/目录。生成的whl文件名会包含包名、版本、Python标签如py3、ABI标签如none和平台标签如any,win_amd64。例如my_awesome_package-0.1.0-py3-none-any.whl。其中py3-none-any表示这是一个纯Python的、跨平台的wheel。对于包含C扩展的项目情况会复杂一些。你需要确保系统有正确的编译环境Windows上通常是Visual Studio或MSVCLinux/macOS上是GCC/Clang。setuptools通过Extension类来定义C扩展# 在setup.py中 from setuptools import setup, Extension module Extension(mypkg.speedup, sources[src/mypkg/speedup.c], include_dirs[/usr/local/include]) setup( ..., ext_modules[module], )运行python setup.py bdist_wheel时setuptools会调用编译器来编译这个C文件。生成的whl文件名会包含平台信息如my_awesome_package-0.1.0-cp39-cp39-win_amd64.whl这意味着它只能在Windows 64位、CPython 3.9的环境下安装。3.2 现代标准方式使用python -m buildPEP 517和518定义了更标准的构建流程不直接调用setup.py而是通过pyproject.toml中指定的构建后端来执行。build包就是这个流程的官方前端工具。首先安装构建工具pip install build然后在项目根目录执行python -m build --wheel这个命令会创建一个独立的、临时的虚拟环境隔离构建环境。根据pyproject.toml中的[build-system]部分安装requires里指定的依赖setuptools和wheel。调用build-backendsetuptools.build_meta来构建wheel。将生成的wheel文件输出到dist/目录。为什么推荐python -m build隔离性构建环境是干净的避免了因全局环境污染导致的构建失败。可重复性在任何机器上只要pyproject.toml一致构建过程就是一致的。标准化它是PEP标准未来所有构建工具都会遵循这个接口。踩坑实录editable安装模式与wheel开发时我们常用pip install -e .可编辑安装这会在site-packages里创建一个链接指向你的源码目录方便边改边测。但请注意可编辑安装模式不会生成wheel文件。它创建的是一个特殊的.egg-link文件或*.pth文件。当你需要分发、测试真正的安装效果时务必先构建wheelpython -m build --wheel然后用pip install dist/your_package.whl来安装这样才能模拟用户真实的安装场景避免一些路径或导入相关的问题在最后时刻才暴露。4. 高级打包场景与疑难排坑掌握了基础打包后你会遇到更实际、更复杂的需求。下面我们拆解几个典型场景。4.1 包含数据文件与资源你的包可能不只是Python代码还需要包含模板、静态文件CSS/JS、预训练模型、默认配置文件等。这些统称为“包数据”Package Data。在pyproject.toml中配置推荐 使用[tool.setuptools.package-data]节进行声明式配置如前面2.2节所示。键是包名值是该包下需要包含的文件路径列表支持通配符。在setup.py中配置 使用package_data参数。setup( ..., package_data{ mypkg: [data/*.json, templates/*.html], mypkg.subpkg: [config/*.yaml], }, include_package_dataTrue, # 同时启用MANIFEST.in文件 )MANIFEST.in文件这是一个更古老但依然有效的机制用于指定在构建源码分发sdist时要包含哪些额外的文件。setuptools在构建wheel时默认也会参考MANIFEST.in但为了清晰和避免混淆对于纯数据文件我强烈建议仅使用package_data配置。MANIFEST.in更适合包含像LICENSE、README.md、tests/等不属于任何Python包但又需要被打进源码包的文件。如何在代码中访问这些数据文件不能直接用相对路径./data/file.json因为安装后文件位置会变。正确的方法是使用importlib.resourcesPython 3.7或pkg_resources较旧但功能更全。# 使用 importlib.resources (现代推荐) import importlib.resources as pkg_resources from mypkg import data # data是一个包含数据文件的子包或目录 # 作为文件路径需要上下文管理器 with pkg_resources.as_file(pkg_resources.files(data).joinpath(config.json)) as config_path: with open(config_path, r) as f: config json.load(f) # 或直接读取内容 config_text pkg_resources.files(data).joinpath(config.json).read_text(encodingutf-8)4.2 处理依赖与可选功能依赖管理是打包的重要一环。install_requires/dependencies这是硬依赖没有它们你的包无法运行。版本范围要写清楚。使用表示最低版本~表示兼容版本如~2.1.0等价于2.1.0, 2.2.0避免使用过于宽泛的*。extras_require/optional-dependencies定义可选功能依赖。例如你的包基础功能只需要requests但有一个需要pandas进行数据分析的模块。你可以定义[project.optional-dependencies] analysis [pandas1.3.0]用户可以通过pip install “my-package[analysis]”来安装这个额外功能。在代码中可以通过try-except导入来提供优雅降级。setup_requires已废弃。用于指定构建时依赖现在应统一在pyproject.toml的[build-system]下的requires中声明。tests_require用于指定运行测试的依赖通常放在extras_require的dev或test组里。4.3 平台特定与条件依赖如果你的包只在特定平台工作或者在不同平台需要不同的依赖可以使用环境标记Environment Markers。[project] dependencies [ pywin32300; sys_platform win32, # 仅Windows需要 pyobjc-core8.0; sys_platform darwin, # 仅macOS需要 some-lib1.0; python_version 3.8, # Python 3.8 需要 ]在setup.py中写法类似install_requires[ pywin32300; sys_platform win32, ]4.4 常见构建错误与排查error: invalid command bdist_wheel原因没有安装wheel包。解决pip install wheel。ModuleNotFoundError: No module named setuptools或Cant findpyproject.tomlorsetup.py原因在错误的目录执行命令或者pyproject.toml中[build-system]配置错误。解决确保在包含pyproject.toml或setup.py的项目根目录运行命令。检查pyproject.toml格式是否正确。打包成功但安装后import失败提示找不到模块原因packages配置错误没有包含你的源码包。或者包结构不符合预期例如使用了src布局但未配置package_dir。排查检查dist/下的whl文件内容unzip -l dist/my_package.whl。看看你的.py文件是否在正确的路径下如my_package/__init__.py。检查pyproject.toml中的[tool.setuptools]或setup.py中的packages和package_dir设置。对于src布局务必设置package_dir {“”: “src”}并使用find_packages(where”src”)。包含C扩展的项目在Windows上构建失败提示Unable to find vcvarsall.bat原因缺少Windows C编译环境。解决方案A推荐安装Visual Studio Build Tools或Visual Studio并勾选“使用C的桌面开发”工作负载。方案B使用预编译的二进制wheel。对于开源项目可以借助CI如GitHub Actions在多种平台上自动构建并上传到PyPI。对于私有项目可以维护一个内部的wheel仓库。版本冲突或依赖解析失败原因你的包声明的依赖版本与用户环境中已安装的包版本冲突。解决在声明依赖时尽量使用宽松但合理的版本范围。使用pip的依赖解析器虽然现在更强大但过于严格的版本限制如2.1.0仍可能给用户带来麻烦。除非有绝对必要否则使用和~。5. 从构建到发布完整工作流与最佳实践构建出whl文件只是第一步一个专业的打包发布流程还包括测试、上传和版本管理。5.1 本地测试与验证在发布前务必进行安装测试# 1. 在全新的虚拟环境中测试安装 python -m venv test_env source test_env/bin/activate # Linux/macOS # test_env\Scripts\activate # Windows pip install dist/my_awesome_package-0.1.0-py3-none-any.whl # 2. 启动Python尝试导入你的包并运行核心功能 python -c “import my_awesome_package; print(my_awesome_package.__version__)” # 运行你的测试套件如果随包安装了 python -m pytest --pyargs my_awesome_package使用tox进行多环境测试tox可以自动为你创建多个虚拟环境例如Python 3.8, 3.9, 3.10在每个环境中构建并安装你的包然后运行测试。这是确保包兼容性的黄金标准。配置一个简单的tox.ini[tox] envlist py38, py39, py310, py311 [testenv] deps pytest6.0 commands python -m pytest tests/运行tox即可。5.2 发布到PyPIPyPI是Python包的官方仓库。发布前你需要注册一个账号。使用twine上传安全推荐安装twinepip install twine构建分发文件源码包和wheel包python -m build上传到测试PyPI先试水twine upload --repository-url https://test.pypi.org/legacy/ dist/*从测试PyPI安装验证pip install --index-url https://test.pypi.org/simple/ my-awesome-package确认无误后上传到正式PyPItwine upload dist/*你需要输入在PyPI上注册的用户名和密码。为了提高安全性建议使用API Token。在PyPI账户设置中生成Token上传时用户名填__token__密码填Token本身。自动化发布与CI/CD 对于开源项目最酷的做法是使用GitHub Actions。你可以配置一个工作流在每次打上Git标签如v0.1.0时自动运行测试、构建wheel并上传到PyPI。网上有大量现成的模板搜索“GitHub Actions Python publish”即可找到。5.3 版本管理与“开发版”打包版本号管理至关重要。我强烈推荐使用setuptools-scm。它可以根据Git仓库的标签和提交历史自动生成版本号。安装pip install setuptools-scm在pyproject.toml中配置[project] name “my-awesome-package” dynamic [“version”] # 声明版本是动态的 [tool.setuptools.dynamic] version {attr “mypkg.__version__”} # 从包中读取需要配合setuptools-scm [tool.setuptools_scm] # setuptools-scm的配置 # 通常无需额外配置默认行为就很好在src/mypkg/__init__.py中如果你用src布局from importlib.metadata import version, PackageNotFoundError try: __version__ version(__name__) except PackageNotFoundError: # 包没有被安装例如在开发模式下 __version__ “0.0.0dev”为发布打标签git tag -a v0.1.0 -m “Release version 0.1.0”然后git push --tags。当你构建时setuptools-scm会自动将标签v0.1.0转换为版本号0.1.0。如果当前提交距离标签还有额外的提交它会生成类似0.1.1.dev5gabc123的开发版本号。对于日常开发你可能不想每次都打标签。可以直接安装为“可编辑模式”pip install -e .进行开发。当需要测试“准发布”状态时再构建wheel进行安装测试。5.4 私有包分发搭建内部PyPI对于公司内部项目你不可能都发布到公开PyPI。这时需要搭建私有PyPI服务器。有几个成熟选择pypiserver轻量级适合小团队。一个命令就能启动。devpi功能强大支持缓存、镜像、持续集成等是更专业的选择。云服务/商业产品如Gemfury、Cloudsmith等提供托管的私有仓库服务。使用私有仓库时用户可以通过pip的--index-url或--extra-index-url参数来指定源或者在pip.conf文件中进行永久配置。打包Python项目成whl文件远不止是运行一条命令。它涉及项目结构的规划、依赖的精准声明、构建流程的标准化以及最终的分发策略。从简单的纯Python库到复杂的带C扩展的项目理解并善用pyproject.toml、setuptools、wheel和build这套工具链能让你交付的软件更加专业、可靠。记住一个好的打包实践是对你代码用户的一份尊重也是项目迈向成熟的重要标志。
