Python包构建遇email.errors.InvalidHeaderDefect错误：如何排查修复？

可能的错误来源及修复方法 #

• 检查所有含Email的字段
  别只盯着project.authors里的email，还要排查maintainers、contact这类字段，甚至部分工具配置项（比如代码检查、测试工具的配置）里如果误填了email格式内容，也可能触发校验。确保所有涉及email的字段都严格遵循xxx@xxx.xxx的格式，没有多余空格、错位引号。示例正确格式：

  [project.authors]
  name = "Your Name"
  email = "your-valid@email.com"
  

• 更新构建工具版本
  旧版的build、setuptools或twine对email的校验逻辑可能存在bug，比如无法识别带加号的合法邮箱（如your+tag@email.com）。执行命令更新工具：

  pip install --upgrade build setuptools twine
  

• 校验toml语法正确性
  有时候email本身没问题，但周围的toml语法错误（比如字符串未闭合、缩进错误、特殊字符未转义）会导致解析异常，被工具误判为email格式问题。可以用toml-lint工具检查文件：

  pip install toml-lint
  toml-lint pyproject.toml
  

• 检查全局配置文件
  构建工具可能读取~/.pypirc、setup.cfg这类全局或本地配置文件中的email信息，如果这些配置里的email格式错误，会干扰pyproject.toml的配置。打开这些文件检查email字段是否合规。

• 简化配置做测试
  临时注释掉pyproject.toml中非必要的配置项，只保留基础项目信息和正确的email，执行python -m build测试。如果构建成功，再逐步恢复其他字段，定位到触发错误的配置。

内容的提问来源于stack exchange，提问作者The Empty String Photographer