向PyPI上传Python包时如何在setup.cfg中指定自定义README文件路径

问题原因 #

你写的long_description = file: Docs/README.md语法本身符合setuptools规范，配置失败通常是两个原因：路径大小写不匹配、打包时未将非根目录的README文件包含进发布包。

正确配置步骤 #

1. 确认setup.cfg的metadata段配置正确，同时补充内容类型声明：

[metadata]
long_description = file: Docs/README.md
# 必须和实际使用的文档格式匹配，md对应text/markdown，rst对应text/x-rst
long_description_content_type = text/markdown

2. 配置打包规则包含子目录的README文件
   在项目根目录新建MANIFEST.in文件，添加如下内容即可将指定路径的文件纳入打包范围：

include Docs/README.md

如果需要批量包含Docs目录下的所有md文件，可以改成：

recursive-include Docs *.md

3. 路径大小写校验
   如果在Windows系统下开发，要注意路径大小写需和实际目录完全一致，PyPI的托管环境为Linux系统，大小写敏感，目录名如果是小写docs，配置里写大写Docs会读取失败。

4. 本地验证配置
   配置完成后本地执行打包命令，检查生成的源码包是否包含目标README文件：

python -m build --sdist

解压dist目录下生成的.tar.gz文件，确认内部存在Docs/README.md即配置无误，可正常上传至PyPI。

如果使用的setuptools版本低于42.0.0，需要先升级到最新版本：pip install --upgrade setuptools

内容的提问来源于stack exchange，提问作者Rainfall.NZ