如何为GCP Artifact Registry中的Python包添加描述？

核心配置与检查步骤 #

• 确认pyproject.toml的元数据字段：Artifact Registry读取Python包描述依赖pyproject.toml的project段落实时解析，必须明确配置以下关键字段：

  [project]
  name = "你的包名"
  version = "0.1.0"
  description = "包的简短描述文本"
  readme = "README.md"
  authors = [
    { name = "你的名称", email = "你的邮箱" }
  ]
  

  其中description是Artifact Registry列表页显示的核心字段，readme需指定正确的文件名（确保文件随包一同上传）。

• 验证本地构建的包元数据：在上传前用工具确认元数据是否正确嵌入包中，执行以下命令：

  • 用twine check dist/*检查构建后的sdist/wheel包，确认描述和README内容被正确识别；
  • 或用pip install --dry-run --no-index --find-links=./dist 你的包名查看本地包的元数据详情。若本地检查就无描述，说明构建环节有问题，与Artifact Registry无关。

• 上传标准格式的包文件：必须通过python -m build生成标准的sdist（.tar.gz）或wheel（.whl）包，再用twine upload --repository-url=https://LOCATION-python.pkg.dev/PROJECT-ID/REPOSITORY/ dist/*完成上传。Artifact Registry仅解析标准包格式中的元数据，直接上传单个文件会导致描述丢失。

• 刷新页面或等待缓存更新：Artifact Registry页面存在缓存机制，描述未显示时可尝试强制刷新（Ctrl+F5），或等待1-2分钟后再查看。

额外排查点 #

• 检查README.md格式：确保文件编码为UTF-8，无Markdown语法错误，可在本地用预览工具确认内容正常；
• 确认仓库配置正确性：上传时使用的仓库URL需对应正确的Python类型仓库，避免传错仓库导致元数据不被解析。

内容的提问来源于stack exchange，提问作者Mike Williamson