README.md 必须放在项目根目录、文件名严格为 README.md，首段用1–3行纯文本说明功能，且 pyproject.toml 中 description 字段需同步填写纯文本摘要，否则 PyPI 页面显示“No description”。
README.md 该写什么、怎么组织才不被 PyPI 忽略
PyPI 不会渲染 README 中的任意 HTML 或复杂嵌套结构，只认标准 Markdown 语法，且对首段摘要极度敏感。如果上传后项目页显示“No description”，大概率是 README.md 缺失、路径不对，或首段没用纯文本写清功能。
必须满足的三点：
-
README.md文件名严格大小写匹配，不能是readme.md或README.MD - 文件需放在项目根目录（和
pyproject.toml同级），不是src/下 - 首段建议控制在 1–3 行纯文字，避免以标题、图片、引用块开头 —— PyPI 提取摘要时会跳过这些
推荐开头写法示例：
my_package: A lightweight utility for parsing ISO 8601 timestamps with timezone-aware validation.
后面再接安装命令、基本用法、API 示例。别把 LICENSE 全文粘进去，放个链接就行。
立即学习“Python免费学习笔记（深入）”；
pyproject.toml 中 [project] 表必须填哪些字段才能通过 twine check
twine check 是上传前必跑的校验工具，它不报错 ≠ PyPI 接收成功，但报错一定拦你。核心元数据字段缺失或格式错误会直接拒绝上传。
以下字段为硬性要求（pyproject.toml 的 [project] 表内）：
-
name：必须全小写、仅含 ASCII 字母/数字/下划线/连字符；不能和 PyPI 上已有包重名 -
version：必须符合 PEP 440 格式，如"0.1.0"、"1.2.3a1"；不能是"dev"或"latest" -
description：纯文本单行摘要，长度建议 ≤ 200 字符；若留空，twine check不报错但 PyPI 页面无描述 -
readme：值必须是字符串"README.md"（或"README.rst"），不能带路径如"docs/README.md" -
requires-python：明确声明支持的 Python 版本范围，如">=3.8"；漏写会导致用户安装失败却无法提示
常见翻车点：authors 写成列表但没用字典格式，例如写成 authors = ["Alice"] 会触发 twine check 警告；正确写法是 authors = [{ name = "Alice", email = "alice@example.com" }]。
Metadata 规范里 classifiers 怎么选才不影响搜索和兼容性判断
PyPI 搜索、IDE 自动补全、CI 环境识别 Python 版本，都依赖 classifiers 字段。它不是装饰项，而是机器可读的关键标签。
必须包含且准确填写的分类器：
-
"Programming Language :: Python :: 3"：所有 Python 3 包都得有，缺了会被标记为“Python 2 only” -
"Programming Language :: Python :: 3.X"（X 替换为你实际支持的最低版本，如3.8）：否则 CI 可能误判环境兼容性 -
"License :: OSI Approved :: MIT License"（或其他对应许可证）：不写或写错会导致 PyPI 不显示许可证图标，影响用户信任 -
"Operating System :: OS Independent"：如果你没用 C 扩展或系统调用，就写这个；写了Microsoft :: Windows却在 Linux 下能跑，反而误导用户
别乱加 "Topic :: Software Development :: Libraries" 这类泛分类 —— 它不参与任何自动逻辑，纯属占位，还可能稀释真实标签权重。
如何验证 .whl 文件里的 METADATA 是否真按规范生成
构建出 .whl 后，别只信 twine check。PyPI 实际读取的是包内 METADATA 文件（位于 my_package-0.1.0.dist-info/ 下），而这个文件由构建后端自动生成，有时会因配置疏漏漏掉字段。
手动验证步骤：
- 用
unzip -l my_package-0.1.0-py3-none-any.whl | grep METADATA确认文件存在 - 用
unzip -p my_package-0.1.0-py3-none-any.whl my_package-0.1.0.dist-info/METADATA | head -n 15查看前几行 - 检查是否含
Name:、Version:、Summary:、Requires-Python:等关键头字段；Summary:值应和pyproject.toml里description一致
注意：Summary: 是从 description 字段拷贝的，不是从 README 首段提取的 —— 很多人以为改了 README 就能更新摘要，其实不会。
