Hatch构建工具v1.26.0版本中license-files配置格式变更解析

在Python项目构建工具Hatch的最新版本v1.26.0中，项目许可证文件的配置格式发生了重要变更。这一变更直接影响了使用Hatch作为构建后端的项目配置方式，需要开发者特别注意。

变更背景

Hatch作为现代Python项目构建工具，对项目元数据（metadata）的配置有着严格的要求。在v1.26.0版本之前，开发者可以通过字典形式配置license-files字段，指定项目中包含的许可证文件路径。然而，这种灵活性可能导致配置不一致性问题。

具体变更内容

新版本中，Hatch强制要求license-files字段必须使用数组（array）格式进行配置。这意味着：

旧版配置方式（v1.26.0之前有效）：

license-files = { paths = ["LICENSE", "IP_NOTICE"] }

新版必须改为：

license-files = ["LICENSE", "IP_NOTICE"]

变更影响

这一变更会导致以下情况：

1. 使用旧格式的项目在v1.26.0及以上版本的Hatch中构建时会抛出TypeError
2. 错误信息明确提示："Field project.license-files must be an array"
3. 构建过程会直接失败，无法生成wheel等分发文件

技术原理

这一变更反映了Hatch团队对项目配置标准化的追求。数组格式相比字典格式：

• 更符合TOML配置文件的常见模式
• 减少了不必要的嵌套层级
• 提高了配置的可读性和一致性
• 与其他构建工具（如setuptools）的配置风格更加统一

解决方案

对于受影响的用户，解决方案非常简单：

1. 检查项目中的pyproject.toml文件
2. 将license-files字段从字典格式改为直接数组格式
3. 确保指定的许可证文件确实存在于项目根目录中

最佳实践建议

1. 对于新项目，直接使用数组格式配置license-files
2. 对于现有项目，在升级Hatch前检查并更新配置
3. 考虑在CI/CD流程中加入配置格式检查
4. 保持许可证文件命名的一致性（推荐使用全大写的LICENSE）

总结

Hatch v1.26.0对license-files配置格式的变更虽然带来了短暂的适配成本，但从长远看提高了项目配置的规范性和可维护性。作为开发者，理解并适应这类构建工具的演进是保持项目健康的重要一环。建议所有使用Hatch的项目都尽快检查并更新相关配置，以确保构建流程的顺畅。