我经常碰到开发者遇到这个问题，核心原因大多和PyPI读取项目描述的配置逻辑有关，下面是一步步的排查和解决方法：

• 检查pyproject.toml的关键配置
  PyPI会从你的pyproject.toml里读取项目的基础描述，同时需要明确指定README文件作为长描述。确保你的配置里包含以下内容：

  [tool.poetry]
  name = "sql2json"
  version = "x.x.x"  # 替换成你的实际版本号
  description = "这里填你的项目简短功能描述"  # 必填项，PyPI会显示在搜索结果里
  readme = "README.md"  # 这行必须加，告诉Poetry把README作为长描述打包
  # 其他作者、依赖等配置...
  

• 验证README的格式兼容性
  PyPI支持Markdown格式的README，但如果你的README里包含GitHub特有的语法（比如某些动态徽章、复杂的折叠块），可能会导致渲染失败，看起来像是描述缺失。你可以用以下命令本地验证：

  • 先运行poetry check，检查pyproject.toml的语法和必填项是否合规
  • 安装twine后运行twine check dist/*，这个工具会模拟PyPI的验证逻辑，提前发现描述渲染问题

• 重新构建并发布
  如果配置没问题，就清理旧的构建产物重新发布：

  1. 删除项目根目录下的dist文件夹
  2. 重新构建：poetry build
  3. 重新发布：poetry publish

  注意：PyPI不允许覆盖已发布的相同版本，如果你之前已经发布过当前版本，需要先在pyproject.toml里升级版本号（比如从0.1.0改成0.1.1）

• 额外排查点
  如果你用的是README.rst而不是README.md，要注意reStructuredText的语法比Markdown严格很多，一点点格式错误就会导致PyPI无法渲染描述，建议优先使用Markdown格式的README。

内容的提问来源于stack exchange，提问作者Francisco Pérez