当使用 pyproject.toml 构建 Python 包时，若通过 pip install xxx.tar.gz 安装源码分发包（sdist）却显示项目名为 UNKNOWN、版本为 0.0.0，通常是因 pip 版本过旧，无法正确解析现代 PEP 621 元数据所致。升级 pip 即可彻底解决。
当使用 `pyproject.toml` 构建 python 包时，若通过 `pip install xxx.tar.gz` 安装源码分发包（sdist）却显示项目名为 `unknown`、版本为 `0.0.0`，通常是因 pip 版本过旧，无法正确解析现代 pep 621 元数据所致。升级 pip 即可彻底解决。
该问题本质是 pip 在构建 wheel 过程中元数据提取失败，而非 pyproject.toml 配置错误。从你的配置可见，[project] 段已正确定义：
[project] name = "myproject_qohelet" version = "1.1" # ... 其他字段
这完全符合 PEP 621 规范，且 python -m build 能成功生成 .whl 文件（你已验证 wheel 安装正常），说明打包流程本身无误。
真正的问题出在 pip 对源码包（.tar.gz）的“就地构建”行为：
当执行 pip install myproject_qohelet-1.1.tar.gz 时，pip 会尝试从源码包中重新构建 wheel —— 此过程需读取 pyproject.toml 并提取 project.name 和 project.version。但 pip ≤ 22.x 版本对纯 pyproject.toml（无 setup.py/setup.cfg）的支持不完整，尤其在元数据预处理（Preparing metadata (pyproject.toml)）阶段会回退到默认值 UNKNOWN 和 0.0.0。
而你观察到 .whl 安装显示正确名称 myproject-qohelet-1.1，正是因为 wheel 文件内已固化了正确的元数据，pip 直接读取即可，无需重建。
✅ 解决方案：升级 pip 至 23.1 或更高版本（推荐 ≥ 24.0）
# 升级 pip（建议使用 --upgrade-strategy eager 确保依赖同步更新） python -m pip install --upgrade --upgrade-strategy eager pip # 验证版本 pip --version # 应输出类似: pip 24.0.1 from ...
升级后，再次安装源码包：
pip install myproject_qohelet-1.1.tar.gz
控制台将正确显示：
Building wheel for myproject_qohelet (pyproject.toml) ... done Created wheel for myproject_qohelet: filename=myproject_qohelet-1.1-py3-none-any.whl Successfully installed myproject_qohelet-1.1
? 额外验证建议（确保配置健壮性）：
- 运行 python -m build --sdist 显式构建源码包，并检查生成的 myproject_qohelet-1.1.tar.gz 内 pyproject.toml 是否完整嵌入（解压后确认）；
- 使用 pip show myproject_qohelet 验证已安装包的元数据是否准确；
- 若团队协作，建议在 requirements-build.txt 中锁定 pip >= 24.0，避免 CI/CD 环境复现问题。
⚠️ 注意：切勿为兼容旧 pip 而降级打包标准（如添加空 setup.py），这违背 PEP 621 设计初衷，且可能引发构建冲突。坚持使用现代 pyproject.toml + 升级工具链，才是可持续的工程实践。
