Windows与Linux下Poetry构建whl文件SHA256不一致问题求助

核心原因 #

wheel本质是zip归档文件，不同系统下构建时，文件的修改时间戳、Unix权限位（Windows不支持）、zip归档的文件顺序差异，都会导致最终wheel文件的哈希值不同——哪怕解压后内容完全一致。

解决方案 #

1. 统一wheel构建规则 #

通过配置强制固定构建时的元数据，避免跨系统差异：

• 在本地包的pyproject.toml中添加Poetry构建配置：

[tool.poetry.build]
generate-setup-file = false

[tool.poetry.build-system]
requires = ["poetry-core>=1.0.0", "wheel>=0.38.0"]
build-backend = "poetry.core.masonry.api"

• 替换构建脚本中的poetry build --format wheel为：

poetry run python -m wheel bdist_wheel --universal --no-update-date

--no-update-date会固定归档内文件的修改时间戳，--universal确保生成跨平台兼容的wheel（若你的包支持）。

2. 手动指定固定哈希值 #

在消费包的pyproject.toml中直接声明本地包的SHA256值，跳过Poetry自动计算：

my_local_package = { path = "./packages/my_local_package-0.1.0-py3-none-any.whl", develop = false, sha256 = "你预先计算好的固定哈希值" }

计算哈希时要使用跨系统一致的工具：

• Windows（PowerShell）：

Get-FileHash -Path .\packages\my_local_package-0.1.0-py3-none-any.whl -Algorithm SHA256 | Select-Object -ExpandProperty Hash

• Ubuntu（bash）：

sha256sum ./packages/my_local_package-0.1.0-py3-none-any.whl | awk '{print $1}'

3. CI/CD复用本地构建的wheel #

避免在CI环境中重新构建wheel，直接使用本地生成的文件：

• 例如在GitHub Actions中，通过actions/upload-artifact上传本地构建的wheel，CI步骤中下载后直接使用，确保跨环境用同一文件。

内容的提问来源于stack exchange，提问作者Lilian Delouvy