Poetry项目构建中.bundle文件缺失问题的分析与解决

在Python项目构建工具Poetry的使用过程中，开发者可能会遇到一个特殊问题：当使用Poetry 2.x版本构建wheel包时，项目中的.bundle文件有时会意外缺失。这个问题在不同操作系统上的表现存在差异，在Windows和macOS平台重现率较高，而在Linux系统上则较难复现。

问题现象

项目构建过程中，虽然pyproject.toml配置文件中已经明确包含了.bundle文件，但生成的wheel包中却找不到该文件。这会导致运行时出现模块缺失的错误，例如"Partition does not exist"等异常。

问题根源

这个问题源于Poetry 2.0.0版本对include行为的重要变更。在2.0.0版本之前，Poetry对于文件的include行为默认会同时包含在sdist和wheel中。但从2.0.0开始，Poetry修改了这一默认行为：

1. 对于未指定格式的include项，默认只包含在sdist中
2. 这一变更旨在使include行为更加一致
3. 文档中明确建议开发者应该显式指定格式而非依赖默认值

解决方案

要确保文件被正确包含在wheel包中，需要在pyproject.toml中明确指定格式。以下是修改前后的配置对比：

修改前：

include = ["dut/dut.bundle"]

修改后：

include = [
    { path = "dut/dut.bundle", format = ["sdist", "wheel"] }
]

跨平台差异的解释

这个问题在不同操作系统上表现不一致的原因可能包括：

1. 文件系统处理差异：不同系统对文件路径和扩展名的处理方式不同
2. 构建环境差异：各平台的Python环境和构建工具链可能存在细微差别
3. 缓存机制影响：Poetry的缓存行为在不同系统上可能有所不同

最佳实践建议

1. 对于需要包含在wheel中的非Python文件，始终显式指定format参数
2. 在CI/CD流程中，建议在不同平台上测试构建结果
3. 对于关键资源文件，考虑添加构建后的验证步骤
4. 定期检查Poetry的更新日志，了解行为变更

总结

Poetry 2.x版本对文件包含行为的变更是有意为之的设计决策，而非bug。开发者需要适应这一变更，通过显式配置来确保文件被正确包含。理解这一机制后，可以避免类似问题的发生，确保项目构建的可靠性。

对于从旧版本迁移的项目，建议仔细检查所有include项，并根据需要添加明确的格式声明，这是保证跨平台构建一致性的关键步骤。