Maturin项目构建Python包时README文件冲突问题解析

Maturin作为Rust与Python互操作的重要工具，在1.7.0版本引入了一个值得开发者注意的构建行为变更。当项目采用workspace模式组织代码时，构建Python包(sdist)过程中会出现README文件路径冲突问题。

问题现象

在workspace项目中，当Rust crate和Python包分别位于不同子目录时，maturin 1.7.0+版本会尝试同时包含根目录和Python子目录下的README.md文件。这导致构建失败，错误信息显示"File was already added"的冲突提示。

典型项目结构如下：

workspace-root/
├── README.md          # 根目录README
├── python/
│   ├── Cargo.toml     # Python包配置
│   ├── README.md      # Python包专用README
└── rust/
    └── cli/
        ├── Cargo.toml # Rust crate配置
        └── README.md  # Rust crate专用README

技术背景

这个问题源于maturin对workspace项目中文件处理的改进。在1.7.0版本前，maturin会优先使用Python子目录下的README；而新版本则尝试同时包含所有相关README文件，导致路径冲突。

Cargo本身也有类似机制，当检测到readme路径指向包外时会发出警告，但允许构建继续。Maturin 1.7.0开始更严格地执行这一规则。

解决方案

开发者可以采取以下几种方式解决：

1. 升级到maturin 1.7.1+：该版本已修复此问题，正确处理workspace中的README文件

2. 明确指定README路径：在pyproject.toml中显式配置readme路径

[tool.maturin]
readme = "python/README.md"

3. 统一README文件：如果项目允许，可以只保留一个README文件在根目录

4. 使用相对路径：确保README路径相对于Python包目录，而非workspace根目录

最佳实践

对于复杂项目结构，建议：

• 为Python包维护独立的README
• 在pyproject.toml中明确指定readme路径
• 保持Rust crate和Python包的文档分离
• 定期检查构建警告，及时处理潜在问题

这个问题提醒我们，在workspace项目中管理多语言组件时，资源文件的组织需要特别考虑构建工具的行为特性。理解工具链如何处理文件包含规则，有助于设计更健壮的项目结构。