遵循Python打包教程后无法从TestPyPI安装sdist包

1. sdist包缺失核心文件或配置错误 #

• 若pyproject.toml未正确声明包路径，sdist会漏掉核心代码，导致安装后找不到模块。检查[project]字段：

  # 普通项目布局
  [project]
  packages = ["your_package"]
  
  # src布局
  packages = [{ include = "your_package", from = "src" }]
  

• 确认构建后端配置正确：
  • Hatchling：

    [build-system]
    requires = ["hatchling>=1.17.0"]
    build-backend = "hatchling.build"
    

  • Setuptools：

    [build-system]
    requires = ["setuptools>=61.0"]
    build-backend = "setuptools.build_meta"
    

2. TestPyPI索引同步或安装参数错误 #

• 上传包后需等待1-2分钟同步，直接安装可能找不到包。
• 安装时必须指定TestPyPI索引，同时给依赖添加PyPI源（TestPyPI没有完整依赖库）：

  pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package-name
  

3. 本地pip缓存干扰 #

• 缓存的旧包信息会导致安装异常，清理后重试：

  pip cache purge
  pip install --no-cache-dir --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package-name
  

4. sdist包损坏 #

• 重新构建并上传：

  # 清理旧构建产物
  rm -rf dist/ build/ *.egg-info
  # 仅构建sdist
  python -m build --sdist
  # 重新上传至TestPyPI
  twine upload --repository testpypi dist/*
  

5. 项目结构不符合打包规范 #

• 确保结构符合Python打包要求，示例：
  • 普通布局：

    your-project/
    ├── pyproject.toml
    ├── your_package/
    │   ├── __init__.py
    │   └── core.py
    └── README.md
    

  • src布局：

    your-project/
    ├── pyproject.toml
    ├── src/
    │   └── your_package/
    │       ├── __init__.py
    │       └── core.py
    └── README.md
    

  结构错误会导致sdist无法正确包含代码，安装后无法导入模块。

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