Poetry项目依赖配置中平台相关路径选择的最佳实践

2025-05-04 05:16:03作者：牧宁李

诗歌(Poetry)是简化Python包管理和依赖处理的得力工具，让你的项目无论何处都能拥有精确的软件栈配置。告别杂乱无章的文件，只需一个`pyproject.toml`，即可整合`setup.py`、`requirements.txt`等的功能。通过直观的项目定义，轻松声明与管理版本依赖，支持精细到版本号的控制，甚至Git仓库直接引用。无论是核心依赖还是可选模块，或是组织良好的开发和文档生成需求，Poetry一手包办。简单的安装方式，全面的文档支持，加上活跃的社区，让Python项目的包装与部署变得前所未有的简单高效。加入千千万万开发者的选择，用Poetry优雅地编织你的Python世界。

项目地址：https://gitcode.com/gh_mirrors/poe/poetry

在Python项目依赖管理中，Poetry是一个广受欢迎的工具，它提供了强大的依赖解析和版本控制功能。本文将深入探讨如何在Poetry项目中针对不同平台架构配置特定的wheel文件路径，这是许多开发者在跨平台开发中常遇到的问题。

问题背景

在跨平台开发环境中，开发者经常需要为不同操作系统和CPU架构提供不同的二进制包。例如，一个团队可能同时使用Intel Mac、M1 Mac和Linux机器进行开发。当依赖包含Rust编译的扩展时，需要为每个平台提供预编译的wheel文件。

常见误区

许多开发者会尝试使用Poetry的platform和platform_machine参数来指定不同平台的wheel路径，例如：

foo = [
    { platform="linux", path = "./wheels/foo/foo-0.1.0-cp311-cp311-manylinux_2_17_x86_642014_x86_64.whl"},
    { platform="linux", platform_machine="arm64", path = "./wheels/foo/foo-0.1.0-cp311-cp311-macosx_11_0_arm64.whl"},
    { platform="linux", platform_machine="x86_64", path = "./wheels/foo/foo-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl"},
]

这种配置会导致Poetry报错，因为platform_machine并不是一个顶层支持的参数，且platform="linux"对于MacOS平台也是不正确的。

正确配置方法

Poetry官方推荐使用Python环境标记(markers)来精确指定平台相关的依赖。正确的配置方式如下：

foo = [
    { platform="linux", path = "./wheels/foo/foo-0.1.0-cp311-cp311-manylinux_2_17_x86_642014_x86_64.whl"},
    { markers = "sys_platform == 'darwin' and platform_machine == 'arm64'", path = "./wheels/foo/foo-0.1.0-cp311-cp311-macosx_11_0_arm64.whl"},
    { markers = "sys_platform == 'darwin' and platform_machine == 'x86_64'", path = "./wheels/foo/foo-0.1.0-cp311-cp311-macosx_11_0_x86_64.whl"},
]

这种配置明确地：